use --output-file insread of --outputFile for geomPipeline.py

Author: qingfengxia

src/python/geomPipeline.py

@@ -3,12 +3,13 @@
 
 """
 After installation by pip/system package manager, `geomPipeline.py` should be on executable PATH
+On Windows, it is not possible to run geomPipeline.py without make a batch file.
 
-`geomPipeline.py  path-to-your-geometry.stp`
+`geomPipeline.py imprint path-to-your-geometry.stp`
 this script will generate a config file, save result into a folder has the name of your geometry file stem
 
 test command line arguments by
-python3 geomPipeline.py --thread-count 4 --tolerance=0.1 --config  --no-merge ../data/test_geometry/test_geometry.stp && scite config.json
+python3 geomPipeline.py imprint --thread-count 4 --tolerance=0.1 --config  --no-merge ../data/test_geometry/test_geometry.stp && scite config.json
 
 you can keep the `config_file_content` dict in `geomPipeline.py` as it is, which will build a default pipeline
 
@@ -19,8 +20,8 @@
 """
 
 USAGE = """
-geomPipeline.py  action[imprint|check|detect|decompose|...] input_filename
-see more details and optional arguments by `geomPipeline.py -h`
+geomPipeline.py  {imprint|check|detect|decompose|...} input_filename
+
 """
 
 import sys
@@ -93,7 +94,7 @@ def geom_add_argument(parser):
 
 ############################### arg parse ###############################
 parser = argparse.ArgumentParser(usage=USAGE)
-# positional argument, the first positional argument can be ignored
+# positional argument, the first positional argument can have a default
 parser.add_argument(
     "action", nargs="?", type=Action, default=Action.imprint, choices=list(Action)
 )

src/python/pppPipelineController.py

@@ -5,10 +5,12 @@
 # created and tested on Sunday March 22, 2020
 
 """
-This is a demonstration of usage of PPP module, using CommandLineProcessor
+This script defines utility functions that can be shared by all pipeline controllers such as GeomPipeline.py.
+By using those functions,  consistent command line argument and config.json header can be achived.
+
+At the end of this script. a demonstration of usage of PPP core module, using CommandLineProcessor.
 ParallelAccessorTest.cpp is a demo (test) of instantiation of ProcessorTemplate class in C++
 
-todo: make it a class, to be reused with GeomPipeline.py
 """
 
 import sys
@@ -17,8 +19,7 @@
 import copy
 from collections import OrderedDict
 from multiprocessing import cpu_count
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+
 
 import argparse
 import shutil
@@ -40,50 +41,58 @@
 
 
 def ppp_add_argument(parser):
-    # the only compulsory arg
+    # call this function after the first positional arg has been added to parser 
+
+    # the second positional arg for input file
     parser.add_argument(
-        "inputFile", help="input data file, detect type from file suffix"
+        "input", help="input data file, detect type from file suffix",
     )
 
     # optional arguments
+    # do not use "nargs=1", it will return args.outputFile as a list instead of string
     parser.add_argument(
-        "-o", "--outputFile", help="output file name (without folder path)"
+        "--working-dir", help="working folder path, by default, the current working folder",
+        dest = "workingDir"
     )
-    # do not use "nargs=1" it will return args.outputFile as a list instead of string
+
     parser.add_argument(
-        "--workingDir", help="working folder path, by default pwd"
+        "-o", "--output-file", help="output file name (without folder path)",
+        dest = "outputFile"
     )
+
     parser.add_argument(
-        "--outputDir",
-        help="output folder path, by default a subfolder in workingDir",
+        "--output-dir",
+        help="output folder path, by default a subfolder in the working dir",
+        dest = "outputDir"
     )
 
     parser.add_argument(
         "--config",
         dest="config_only",
         action="store_true",
-        help=" only generate config.json without run the pipeline",
+        help=" only generate config.json without run the pipeline processors",
     )
 
-    parser.add_argument(
-        "-v",
-        "--verbosity",
-        type=str,
-        default="INFO",
-        help="verbosity: for console or termimal: DEBUG, PROGRESS, INFO, WARNING, ERROR",
-    )
     parser.add_argument(
         "-nt",
         "--thread-count",
         dest="thread_count",
         type=int,
         default=cpu_count(),
-        help="number of thread to use, max = hardware core number",
+        help="number of thread to use, by default, hardware core number",
     )
-    return (
-        parser  # must return parser, otherwise, modification to input parser will lost
+
+    parser.add_argument(
+        "-v",
+        "--verbosity",
+        type=str,
+        default="INFO",
+        help="verbosity: for console or terminal: DEBUG, PROGRESS, INFO, WARNING, ERROR",
     )
 
+    # must return parser, otherwise, modification to input parser will lost
+    return parser  
+
 
 ############################ input and output ##############################
 def is_url(s):
@@ -94,18 +103,18 @@ def is_url(s):
 
 
 def ppp_parse_input(args):
-    if args.inputFile:
-        if is_url(args.inputFile):
+    if args.input:
+        if is_url(args.input):
             # download to current folder
             import urllib.request
 
-            urllib.request.urlretrieve(args.inputFile, "input_data")
+            urllib.request.urlretrieve(args.input, "input_data")
             return "input_data"
 
-        elif os.path.exists(args.inputFile):
-            return args.inputFile
+        elif os.path.exists(args.input):
+            return args.input
         else:
-            raise IOError("input file does not exist: ", args.inputFile)
+            raise IOError("input file does not exist: ", args.input)
     else:
         raise Exception("input file must be given as an argument")
 
@@ -173,22 +182,19 @@ def ppp_post_process(args):
             print("failed to create symbolic link", linkToInputFile)
 
 
-#####################################################
-
-
 def generate_config_file(config_file_content, args):
     # parse args first, the write config file
 
     config_file_given = False
     generated_config_file_name = "config.json"
     # input json file is config, but not geomtry input manifest file
-    if args.inputFile.find(".json") > 0:
-        with open(args.inputFile, "r") as f:
+    if args.input.find(".json") > 0:
+        with open(args.input, "r") as f:
             _json_file_content = json.loads(f.read())
             # check compulsory key in config.json file
             if "readers" in _json_file_content:
                 config_file_given = True
-                input_config_file_name = args.inputFile
+                input_config_file_name = args.input
             else:
                 pass  # it is a multiple geometry-material manifest json file
     #
@@ -242,7 +248,7 @@ def generate_config_file(config_file_content, args):
     },
 }
 
-###############################################################################
+######################### module specific pipeline control ############################
 
 
 class PipelineController(object):

wiki/GetStarted.md

@@ -1,22 +1,52 @@
 ## Get Started
 
-### Quick start
-The command line `geomPipeline.py imprint your_geometry_file_path` is the starting point for users, just replace *your_geometry_file_path* by your geometry. 
-
-run `geomPipeline.py -h` for more options. 
+### Command line interface
+
+Geometry pipeline can be started in a terminal. `geomPipeline.py` takes 2 positional arguments, the first is the action, and the second is the input file path. For example,  `geomPipeline.py imprint your_geometry_file_path` ,  just replace *your_geometry_file_path* by your geometry. 
+
+Optional arguments for all pipelines, it is expected other pipelines also follow this convention.
+```
+  -h, --help            show this help message and exit
+  -o OUTPUT_FILE, --output-file OUTPUT_FILE
+                        output file name (without folder path)
+  --working-dir WORKING_DIR
+                        working folder path, by default the current working folder
+  --output-dir OUTPUT_DIR
+                        output folder path, by default, a subfolder in workingDir
+  --config              only generate config.json without run the pipeline
+
+  -nt THREAD_COUNT, --thread-count THREAD_COUNT
+                        number of thread to use, max = hardware core number
+
+  -v VERBOSITY, --verbosity VERBOSITY
+                        verbosity: for console or terminal: DEBUG, PROGRESS, INFO, WARNING, ERROR
+```
+
+optional arguments for geometry pipeline
+```
+  --metadata METADATA   input metadata file, only for brep input geometry
+  --tolerance TOLERANCE
+                        tolerance for imprinting, unit MilliMeter
+  --no-merge            do not merge the imprinted shapes, for two-step workflow
+  --ignore-failed       ignore failed (in BOP check, collision detect, etc) solids
+```
+
+Always run `geomPipeline.py -h` to get the latest arguments.  
 
 ### Geometry preprocessing features
 
-The default action is **imprint**, outputting a geometry file (`*._processed.brep`) of one shape with duplicated shared faces removed, and also a `*_processed_metadata.json` file of meta data.  The latter file contains meta data such as material information for the geometry brep file. All the output files are located in a folder in the current directory.
+Implemented geometry processing actions are: `check,detect,merge,imprint,search`, some other planned actions `tessellate, fix, decompose` can be found in [Roadmap.md](Roadmap.md)
+
+The  **imprint** action outputs a geometry file (`*._processed.brep`) of one shape with duplicated shared faces removed, and also a `*_processed_metadata.json` file of meta data.  The latter file contains meta data such as material information for the geometry brep file. All the output files are located in a folder in the current directory.
 
-The imprint operation can be split into 2 steps:  Imprint faces and Merge faces:
+The imprint operation is accomplished in 2 steps:  Imprint faces and Merge faces:
 `geomPipeline.py imprint geometry_file --thread-count 6  --no-merge`
 `geomPipeline.py merge  /home/qxia/Documents/StepMultiphysics/parallel-preprocessor/result --thread-count 6`
 
-Other actions are `search, check, detect, decompose`, etc, see more options by running `geomPipeline.py -h`. 
+Usage of other actions such as `search, check, detect, decompose`
 
 `geomPipeline.py check geometry_file` will check for errors, e.g. volume too small, invalid geometry, etc
-`geomPipeline.py detect geometry_file` will detect collision between solid shapes, see more shape relations types at Geom::CollisionType
+`geomPipeline.py detect geometry_file` will detect collision between solid shapes, see more shape spatial relationship types defined in the type `Geom::CollisionType`
 
 ### Input geometry format supported
 
@@ -29,23 +59,28 @@ Other actions are `search, check, detect, decompose`, etc, see more options by r
      {"material": "Steel",  "filename": "path_to_geometry_file2" },
     ]
   ```
+  see doxygen generate document for this class for most updated information <>
 
-### Advanced usage (adjust pipeline parameters)
-####  Pipeline configuration generation (python script)
 
-`geomPipeline.py` will generate a json configuration based on user input (by default `config.json` in the current folder),  then starts the geometry preprocessing pipeline. For example, the imprint action will be organized into a pipeline of several GeometryProcessors, with default parameters written into the `config.json`. If the output is not ideal, users can edit parameters in the generated `config.json` and re-run the pipeline by `python3 geomPipeline.py config.json`, or equally `geomPipeline path_to_json_config.json`.  
+### Debug your installation
 
-In fact, python pipeline controller such as `geomPipeline.py` generates input configuration, all the processing computation is done by `geomPipeline` which is an executable compiled from C++ code. This executable only accepts a json configuration file, e.g. `geomPipeline path_to_json_config.json`.  
+`which geomPipeline` on Unix-like system, or `where geomPipeline` on Windows to see if executable has been installed on PATH. 
 
-The split of high-level user-oriented python script and lower-level C++ program has the benifits:
-+ to ease the debugging of mixed python and C++ programming
-+ to ease the parallel programming, since Python has the GIL problem
+NOTE:  if installed using deb/rpm on ubuntu and fedora, while user has anaconda activated, then user will not be able to use c-extension module `ppp`. For example, on Ubuntu the ppp module `ppp.cpython-36m-x86_64-linux-gnu.so` is installed to `/usr/lib/python3/dist-packages/`. In that case, `python3 /usr/bin/geomPipeline.py manifest.json` will start an external process by python to run pipeline without using `ppp` module.
 
+On windows, a batch file calling may be generated to run python script "geomPipeline.py" without "python path_to/geomePipeline.py".
 
-### Debug your installation
 
-NOTE:  if installed using deb/rpm on ubuntu and fedora, while user has anaconda activated, then user should give the full path of system python3 path, as the Linux package of ppp link  to system python `/usr/bin/python3`, and install ppp module to system python site. For example, on Ubuntu the ppp module `ppp.cpython-36m-x86_64-linux-gnu.so` is installed to `/usr/lib/python3/dist-packages/`
+### Advanced usage (adjust pipeline parameters)
+####  Pipeline configuration generation (python script)
+
+`geomPipeline.py` will generate a json configuration based on user input (by default `config.json` in the current folder),  then starts the geometry preprocessing pipeline. For example, the imprint action will be organized into a pipeline of several GeometryProcessors, with default parameters written into the `config.json`. 
+
+If the output is not ideal, users can edit parameters in the generated `config.json` and re-run the pipeline by `python3 geomPipeline.py config.json`, or equally `pppGeomPipeline path_to_json_config.json`.  
 
-To use `geomPipeline.py`
+Actually, all the processing computation is done by `pppGeomPipeline` which is an executable compiled from C++ code. This executable only accepts a json configuration file, e.g. `pppGeomPipeline path_to_json_config.json`.  
+
+The split of high-level user-oriented python script and lower-level C++ program has the benefits:
++ to ease the debugging of mixed python and C++ programming
++ to ease the parallel programming, since Python has the GIL problem
 
-`/usr/bin/python3 /user/bin/geomPipeline.py manifest.json`