Merge pull request #19 from qingfengxia/dev

update GetStarted.md  and 2  commits on rename

Author: qingfengxia

src/Geom/CMakeLists.txt

@@ -46,7 +46,7 @@ add_executable(MyGeomMain "GeometryMain.cpp")
 add_dependencies(MyGeomMain MyGeom)
 
 target_link_libraries(MyGeomMain MyGeom)
-set_target_properties(MyGeomMain PROPERTIES OUTPUT_NAME "geomPipeline")
+set_target_properties(MyGeomMain PROPERTIES OUTPUT_NAME "pppGeomPipeline")
 
 if(MSVC)
     target_compile_options(MyGeomMain PRIVATE /wd4996 /wd4251)

src/Geom/GeometryMain.cpp

@@ -11,7 +11,7 @@ int main(int argc, char* argv[])
     if (argc < 2)
     {
         std::cout << "Error: input config file is not provided" << std::endl;
-        std::cout << "Usage: geomPipeline config.json" << std::endl;
+        std::cout << "Usage: pppGeomPipeline config.json" << std::endl;
         std::terminate();
     }
     auto p = new Geom::GeometryPipelineController(argc, argv);

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):

src/python/pppStartPipeline.py

@@ -3,14 +3,14 @@
 
 """
 this enable test for the cases: test after package installed or test in the build folder
-using ppp module is importable, otherwise use the executable: geomPipeline
+using ppp module is importable, otherwise use the executable: pppGeomPipeline
 """
 
 import shutil
 import sys
 import os.path
 
-ppp_geom_executable = "geomPipeline"
+ppp_geom_executable = "pppGeomPipeline"
 
 try:
     import ppp  # in case this python module has been installed
@@ -28,10 +28,10 @@
     try:
         import ppp  # in case of running this module in the build folder
     except ImportError:
-        print("parallel-preprocessor python module `ppp` is not installed/importable")
+        # print("parallel-preprocessor python module `ppp` is not installed/importable")
         # print("if not installed, ppp module must be located in build folder")
         # print("../lib/ related to this script")
-        print("start to run `geomPipeline config.json`in an external process")
+        # print("start to run `pppGeomPipeline config.json`in an external process")
         ppp = None
 
 has_ppp_module = bool(ppp)

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`

wiki/Packaging.md

@@ -142,7 +142,7 @@ First of all, I create release tag, then upload binary package manually (creatin
 then run this action to update the package on each push. 
 
 ```yml
-    # those release asset filename (is created mannually before running this action)
+    # those release asset filename (is created manually before running this action)
     - name: Upload binary package to release
       uses: svenstaro/upload-release-action@v2
       with:

wiki/Testing.md

@@ -1,4 +1,13 @@
 ## Testing
+
+### Run all the tests
+
+After out of source build,  in the build folder such as `parallel-preprocessor/build/`, run `sh run_all_tests.sh`. 
+
+NOTE: unit test application such as `pppGeomTests` must be run in the `build/ppptest` folder for the moment, since test data in `parallel-preprocessor/build/data` are referred using relative path. 
+
+### Tested platforms
+
 Unit tests are written in C++ to test C++ functions and in Python to test the pipeline.
 
 Unit tests can be triggered by `run_all_test.sh` in the build dir. This `run_all_test.sh` will make `ppptest` subfolder under the build folder if not yet generated by cmake build system, and copy/link necessary test data for all tests.
@@ -25,7 +34,7 @@ Those python tests script implement `unittest` paradigm; python3-pytest will be
 
 ### Continuous integration
 
-Gitlab runners ubuntu and fedora setup within UKAEA
+Github CI runners ubuntu and fedora will run all the tests.
 
 
 ### Coverage report in HTML