major refactoring

Gliptal · Sep 1, 2017 · 648b723 · 648b723
1 parent 5d0899b
commit 648b723
Show file tree

Hide file tree

Showing 21 changed files with 539 additions and 388 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,5 +6,5 @@ __pycache__
 *.spec
 verpatch.exe
 
-#privacy
+#private
 ranges.yaml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,61 +1,86 @@
-#### 0.1.0
+#### [1.0.0-rel1](https://github.com/Gliptal/taser/releases/tag/1.0.0-rel1) | *2017-09-01*
 
-+ project skeleton
+- **added:**
+-- coordinates program mode
+- **changed:**
+-- documentation
+-- automated scripts refactoring
+-- code refactoring
+-- arguments logic
 
-#### 0.2.0
+#### 0.10.1 | *2017-03-17*
 
-+ targets data
-+ argument parsing
-+ arguments checking
+- **fixed:**
+-- automated scripts
 
-#### 0.3.0
+#### 0.10.0 | *2017-03-14*
 
-+ units conversions
-+ xml template
-+ wire output
+- **added:**
+-- test script
+-- make script
+-- xml nodes ordering
+-- debug argument
 
-#### 0.4.0
+#### [0.9.0-beta3](https://github.com/Gliptal/taser/releases/tag/0.9.0-beta3) | *2017-03-06*
 
-+ altitude blocks output
+- **added:**
+-- aim-off distance argument
+- **fixed:**
+-- wire origin
+-- heading
 
-#### 0.5.0
+#### [0.8.0-beta2](https://github.com/Gliptal/taser/releases/tag/0.8.0-beta2) | *2017-03-06*
 
-+ code refactoring
-+ coordinates shifter
-+ leeway parameters
+- **added:**
+-- declutter argument
+- **fixed:**
+-- wire angle
+-- heading
 
-#### 0.6.0-beta1
+#### 0.7.0 | *2017-02-24*
 
-+ usage documentation
-+ minor bugfixes
-+ heading fix
-+ heading override
-+ conventional ranges data
-+ better rendering
+- **changed:**
+-- better arguments
 
-#### 0.7.0
+#### [0.6.0-beta1](https://github.com/Gliptal/taser/releases/tag/0.6.0-beta1) | *2017-02-24*
 
-+ better usage flags
+- **added:**
+-- documentation
+-- ranges data
+-- heading override argument
+- **changed:**
+-- better rendering
+- **fixed:**
+-- heading
 
-#### 0.8.0-beta2
+#### 0.5.0 | *2017-02-23*
 
-+ wire angle fix
-+ heading fix
-+ declutter option
+- **added:**
+-- coordinates shifting
+-- leeway arguments
+- **changed:**
+-- code refactoring
 
-#### 0.9.0-beta3
+#### 0.4.0 | *2017-02-23*
 
-+ wire origin fix
-+ aim-off distance option
-+ heading fix
+- **added:**
+-- altitude blocks output
 
-#### 0.10.0
+#### 0.3.0 | *2017-02-22*
 
-+ make script
-+ test script
-+ xml nodes ordering
-+ debug option
+- **added:**
+-- output template
+-- wire output
+-- units conversions
 
-#### 0.10.1
+#### 0.2.0 | *2017-02-22*
 
-+ automated scripts fix
+- **added:**
+-- ranges template
+-- arguments parsing
+-- arguments validation
+
+#### 0.1.0 | *2017-02-22*
+
+- **added:**
+-- project skeleton
diff --git a/README.md b/README.md
@@ -1,12 +1,24 @@
+- [TASER](https://github.com/Gliptal/taser#taser)
+- [INSTALL](https://github.com/Gliptal/taser#install)
+- [USAGE](https://github.com/Gliptal/taser#usage)
+- [EXAMPLES](https://github.com/Gliptal/taser#examples)
+- [BUILD](https://github.com/Gliptal/taser#build)
+- [DATA](https://github.com/Gliptal/taser#data)
+- [CHANGELOG](https://github.com/Gliptal/taser#changelog)
+- [CONTACTS](https://github.com/Gliptal/taser#contacts)
+- [LICENSE](https://github.com/Gliptal/taser#license)
+
 TASER
 ======
 
-**TA**cview **S**l**E**ds **R**enderer: dynamically generate `.xml` files to visually render SLED attack profiles in the Tacview 3D environment. This tool will generate the attack wire, and track, release, abort, and floor altitude blocks relative to a specific target in a specific NTTR conventional range.
+**TA**cview **S**L**E**Ds **R**enderer: dynamically generate [Tacview](http://www.tacview.net/) `.xml` files to render SLED attack profiles. All SLEDs parameters must be specified using the "SLED parameters" [flags](https://github.com/Gliptal/taser#usage); the target can be chosen from the conventional NTTR ranges ("range" option), or specified through a set of lat/lon coordinates ("coord" option). The resulting .xml renders in Tacview the ideal attack wire, among all relevant decision altitudes; leeway options are also available to restrict or relax the rendered wire's constraints.
+
+![tacview](http://i.imgur.com/fM73mBE.jpg)
 
 INSTALL
 ======
 
-[Download](https://github.com/Gliptal/taser/releases) the latest release.
+Download the latest [release](https://github.com/Gliptal/taser/releases) (1.0.0-rel1).
 
 Place `taser.exe` inside Tacview's `Data/Static Objects` folder:
 
@@ -15,16 +27,14 @@ Place `taser.exe` inside Tacview's `Data/Static Objects` folder:
 USAGE
 ======
 
-Open an elevated (administrator) cmd window in the folder:
+Open an elevated ("as administrator") command prompt (or PowerShell) window in Tacview's `Data/Static Objects` folder:
 
 ![admin](http://i.imgur.com/WdNJzux.jpg)
 
-Execute the application by typing `taser.exe` and passing all required and any optional parameters:
+Run `taser.exe` by passing all required and any optional parameters (see [CLI](https://github.com/Gliptal/taser#cli)):
 
 ![cmd](http://i.imgur.com/ifD7Y0Z.jpg)
 
-If no errors occur the application will generate an `.xml` and exit:
-
 ![result](http://i.imgur.com/VuHqmKg.jpg)
 
 Analyze your attack runs with Tacview:
@@ -34,68 +44,110 @@ Analyze your attack runs with Tacview:
 CLI
 ======
 
-`taser.py [-h] [-v] [-fn str] [-la ft] [-lh °] [-ah °] [-dc] -bd nm -ba ft -ta ft -ra ft -aa ft -ma ft range target`
-
-`range` is the short name of the range containing the target (e.g. "64C")
-
-`target` is the name of the target, with dashes "-" replacing spaces " " (e.g. "West-Bomb-Circle")
-
-| flag | shorthand | purpose |
-| :---: | :---: | --- |
-| --help | -h | show the help message |
-| --version | -v | show the version number |
-| --debug | -d | show more exhaustive error messages |
-
-| required | flag | shorthand | purpose | unit | default |
-| :---: | :---: | :---: | --- | :---: | :---: |
-| Y | --basedist | -bd | SLED's *base* distance | nm | |
-| Y | --basealt | -ba | SLED's *base* MSL altitude | ft | |
-| Y | --trackalt | -ta | SLED's *track* MSL altitude | ft | |
-| Y | --releasealt | -ra | SLED's *release* MSL altitude | ft | |
-| Y | --abortalt | -aa | SLED's *abort* MSL altitude | ft | |
-| Y | --minalt | -ma | SLED's *mimimum* MSL altitude | ft | |
-| Y | --aimdist | -ad | *aim-off* distance | ft | |
-| | --leewayalt | -la | available +/- leeway for the SLED's *base*, *track*, and *release* altitudes | ft | 200ft |
-| | --leewayhdg | -lh | available +/- leeway for the range's attack heading at the SLED's *base* altitude | ° | 10° |
-| | --attackhdg | -ah | required attack heading, overrides the range's default | ° | |
-| | --declutter | -dc | declutter the target area by rendering the *abort* and *minimum* altitudes as planes | | |
-| | --filename | -fn | name of the generated `.xml` file | | "sled" |
-
-FRAMEWORK
+`taser.exe [-h] [-v] [-d] [-f :str] [-c] [-ah :°] [-lh :°] [-la :ft] -ad :ft -bd :nm -ba :ft -ta :ft -ra :ft -aa :ft -ma :ft {range,coords}`
+
+```
+optional arguments:
+  -h, --help                 show this help message and exit
+  -v, --version              show program's version number and exit
+  -d, --debug                show detailed error messages
+  -f :str, --filename :str   specify the name of the output file [default:
+                             "sled"]
+  -c, --declutter            declutter the abort and minimum altitudes
+                             rendering
+
+other parameters (optional):
+  -ah :°, --attackhdg :°     specify the attack heading (overrides the range's
+                             default in "range" mode) [°]
+  -lh :°, --leewayhdg :°     specify the leeway left and right of the attack
+                             heading at the SLED's base altitude [° | default:
+                             10°]
+  -la :ft, --leewayalt :ft   specify the leeway above and below the SLED's
+                             base, track, and release altitudes [ft | default:
+                             200ft]
+
+SLED parameters (required):
+  -ad :ft, --aimdist :ft     SLED's aim-off distance [ft]
+  -bd :ft, --basedist :ft    SLED's base distance [ft]
+  -ba :ft, --basealt :ft     SLED's base altitude [ft MSL]
+  -ta :ft, --trackalt :ft    SLED's track altitude [ft MSL]
+  -ra :ft, --releasealt :ft  SLED's release altitude [ft MSL]
+  -aa :ft, --abortalt :ft    SLED's abort altitude [ft MSL]
+  -ma :ft, --minalt :ft      SLED's minimum altitude [ft MSL]
+
+target mode:
+  {range,coords}
+    range                    choose the target from those in the conventional
+                             NTTR ranges
+    coords                   specify the target through a set of lat/lon
+                             coordinates
+```
+
+`taser.exe range [-h] code target`
+
+```
+positional arguments:
+  code        the code of the range
+  target      the name of the target
+
+optional arguments:
+  -h, --help  show this help message and exit
+```
+
+`taser.exe coords [-h] latitude longitude`
+
+```
+positional arguments:
+  latitude    the latitude coordinate of the target [xx.xx.xx.N]
+  longitude   the longitude cooordinate of the target [xxx.xx.xx.W]
+  altitude    the altitude of the target [ft MSL]
+
+optional arguments:
+  -h, --help  show this help message and exit
+```
+
+EXAMPLES
 ======
 
-Development framework powered by [python](https://www.python.org/) and the following non-embedded plugins:
+82_30DB4 SLED on West Bomb Circle in range 64C, default range attack heading, 15° leeway at wire entry:
+
+![82_30DB4](http://i.imgur.com/5MMawCX.png)
+
+`taser.exe -c -lh 15 -ad 1600 -bd 8507 -ba 8700 -ta 7100 -ra 6200 -aa 5900 -ma 4000 range 64C West-Bomb-Circle`
+
+B2_30DB2 SLED on a target located at 35°10'22"N 116°50'11"W @ 5000ft MSL, 90° attack heading:
 
-+ [colorclass](https://pypi.python.org/pypi/colorclass)
-+ [dicttoxml](https://pypi.python.org/pypi/dicttoxml)
-+ [geopy](https://github.com/geopy/geopy)
-+ [PyYAML](http://pyyaml.org/)
-+ [yamlordereddictloader](https://pypi.python.org/pypi/yamlordereddictloader/0.1.1)
+![B2_30DB2](http://i.imgur.com/sQStBo5.png)
+
+`taser.exe -c -ah 90 -ad 1000 -bd 7898 -ba 9900 -ta 8300 -ra 7400 -aa 7100 -ma 6000 coords 35.10.22.N 116.50.11.W 5000`
 
 BUILD
 ======
 
-`.exe` packaging powered by [PyInstaller](http://www.pyinstaller.org/):
+Development framework powered by [python](https://www.python.org/) and the following plugins:
+- [colorclass](https://pypi.python.org/pypi/colorclass)
+- [dicttoxml](https://pypi.python.org/pypi/dicttoxml)
+- [geopy](https://github.com/geopy/geopy)
+- [PyYAML](http://pyyaml.org/)
+- [yamlordereddictloader](https://pypi.python.org/pypi/yamlordereddictloader)
 
+`.exe` packaging powered by [PyInstaller](http://www.pyinstaller.org/):
 `pyinstaller --clean --workpath="../build" --distpath="../dist" --specpath="../dist" --add-data="../source/data;data" --onefile --icon="../dist/icon.ico" taser.py`
 
 `.exe` versioning powered by [Simple Version Resource Tool](https://www.codeproject.com/articles/37133/simple-version-resource-tool-for-windows):
+`verpatch.exe dist/taser.exe /va /langid 0x0809 /high x.x.x /s desc "Generate Tacview .xml files to render SLED profiles." /s product "TAcview SLEDs Renderer" /s copyright "CC Attribution-ShareAlike 4.0" /pv "x.x.x-x"`
 
-`verpatch.exe taser.exe /va /langid 0x0809 /high x.x.x-x /s desc "Generate Tacview .xml files to render SLED profiles." /s product "TAcview SlEds Renderer" /s (c) "CC Attribution-ShareAlike 4.0" /pv "x.x.x.x"`
-
-Automated `make.bat` and `test.bat` scripts can be ran from the root folder.
+Automated `make.bat` and `test.bat` scripts can and must be ran from the project's root folder.
 
 DATA
 ======
 
-The full targets data is not available in this public repository. Contact the [476th vFG](http://www.476vfightergroup.com/content.php) for further information.
+The ranges data is not available in this public repository. Contact the [476th vFG](http://www.476vfightergroup.com/content.php) for further information.
 
 CHANGELOG
 ======
 
-Versioning follows [semantic versioning](http://semver.org/) rules.
-
-[CHANGELOG.MD](https://github.com/Gliptal/tsr/blob/master/CHANGELOG.md)
+[CHANGELOG.md](https://github.com/Gliptal/tsr/blob/master/CHANGELOG.md) versioning follows [semantic versioning](http://semver.org/) rules.
 
 CONTACTS
 ======
@@ -108,5 +160,4 @@ LICENSE
 [![license](https://i.creativecommons.org/l/by-sa/4.0/80x15.png)](http://creativecommons.org/licenses/by-sa/4.0/)
 
 Taser by [Mattia Affabris](mailto:[email protected]) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-sa/4.0/).
-
 Based on a work at [https://github.com/Gliptal/taser](https://github.com/Gliptal/taser).
diff --git a/dist/taser.exe b/dist/taser.exe
diff --git a/make.bat b/make.bat
@@ -1,22 +1,30 @@
 @ECHO OFF
 
-DEL dist\taser.exe 2> nul
+DEL   dist\taser.exe 2> nul
 START /WAIT pyinstaller --clean --workpath="build" --distpath="dist" --specpath="dist" --add-data="../source/data;data" --onefile --icon="dist/icon.ico" source/taser.py
-START /WAIT dist/verpatch.exe dist/taser.exe /va /langid 0x0809 /high %1 /s desc "Generate Tacview .xml files to render SLED profiles." /s product "TAcview SlEds Renderer" /s (c) "CC Attribution-ShareAlike 4.0" /pv %2
+START /WAIT dist/verpatch.exe dist/taser.exe /va /langid 0x0809 /high %1 /s desc "Generate Tacview .xml files to render SLED profiles." /s product "TAcview SLEDs Renderer" /s copyright "CC Attribution-ShareAlike 4.0" /pv %2
 RMDIR /S /Q build 2> nul
+
 IF EXIST dist\taser.exe (
-    DEL test\generated.xml 2> nul
-    CD dist
-    START /WAIT taser.exe 64C West-Bomb-Circle -bd 6039 -ba 9800 -ta 7400 -ra 6200 -aa 5700 -ma 4035 -ad 640 -lh 10 -dc -fn ../test/generated
-    CD ..\test
-    FC correct.xml generated.xml > nul 2> nul
+    CD    dist
+
+    DEL   ..\test\generated.xml 2> nul
+    START /WAIT taser.exe -d -f ../test/generated -c -lh 10 -ad 640 -bd 6039 -ba 9800 -ta 7400 -ra 6200 -aa 5700 -ma 4035 range 64C West-Bomb-Circle
+    FC    ..\test\correct.xml ..\test\generated.xml > nul 2> nul
     IF %ERRORLEVEL% EQU 0 (
-        ECHO [+]    success
+        ECHO [+]    "range" success
+    ) ELSE (
+        ECHO [-]    "range" generating
     )
-    ELSE (
-        ECHO [-]    generating
+
+    DEL   ..\test\generated.xml 2> nul
+    START /WAIT taser.exe -d -f ../test/generated -c -ah 355 -lh 10 -ad 640 -bd 6039 -ba 9800 -ta 7400 -ra 6200 -aa 5700 -ma 4035 coords 36.40.51.N 115.40.26.W 3035
+    FC    ..\test\correct.xml ..\test\generated.xml > nul 2> nul
+    IF %ERRORLEVEL% EQU 0 (
+        ECHO [+]    "coords" success
+    ) ELSE (
+        ECHO [-]    "coords" fail
     )
-    CD ..
 ) ELSE (
-    ECHO [-]    freezing
+    ECHO [-]    packaging
 )