Update readme and changelog

w1th0utnam3 · w1th0utnam3 · commit b99fcbbfbed9 · 2023-04-18T20:15:12.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,8 @@ The following changes are present in the `main` branch of the repository and are
  - Lib: Rename `AxisAlignedBoundingBox*d` typedefs to `Aabb3d` and `Aabb2d` 
  - Lib: Support reading VTU (VTK XML) files
  - CLI: Support reconstruction of particles from VTU (VTK XML) files, including attributes
+ - CLI: Support for specifying an output pattern (e.g. "surface_{}.obj") using `--output-file`/`-o` when processing sequences of files, this allows to specify a different output format than VTK for sequences (which was the only available output format for sequences before)
+ - CLI: Files belonging to a sequence are now detected by treating the placeholder "{}" as a "(\d+)" regex (i.e. any number of digits) and sorting the matching files lexicographically (previously, the tool just counted up from 1) 
 
 ## Version 0.8.0
 
diff --git a/README.md b/README.md
@@ -80,7 +80,7 @@ In the future, flags may be added to switch the internal data structures to use
 
 Note that for small numbers of fluid particles (i.e. in the low thousands or less) the multi-threaded implementation may have worse performance due to the task based parallelism and the additional overhead of domain decomposition and stitching.
 In this case, you can try to disable the domain decomposition. The reconstruction will then use a global approach that is parallelized using thread-local hashmaps.
-For larger quantities of particles the decomposition approach will be faster however.
+For larger quantities of particles the decomposition approach will be faster, however.
 
 As shown below, the tool can handle the output of large simulations.
 However, it was not tested with a wide range of parameters and may not be totally robust against corner-cases or extreme parameters.
@@ -162,22 +162,34 @@ With these parameters, a scene with 13353401 particles is reconstructed in less
 
 You can either process a single file or let the tool automatically process a sequence of files.
 A sequence of files is indicated by specifying a filename with a `{}` placeholder pattern in the name.
-The tool will then process files by replacing the placeholder with indices starting with `1` until a file with the given index does not exist anymore.
+The tool will treat the placeholder as a `(\d+)` regex, i.e. a group matching to at least one digit.
+This allows for any zero padding as well as non-zero padded incrementing indices.
+All files in the input path matching this pattern will then be processed in lexicographical order (i.e. silently skipping missing files in the sequence).
 Note that the tool collects all existing filenames as soon as the command is invoked and does not update the list while running.
 
 By specifying the flag `--mt-files=on`, several files can be processed in parallel.
-Note that you should ideally also set `--mt-particles=off` as enabling both will probably degrade performance.
+If this is enabled, you should ideally also set `--mt-particles=off` as enabling both will probably degrade performance.
+The combination of `--mt-files=on` and `--mt-particles=off` can be faster if many files with only few particles have to be processed.
 
 ## Input file formats
 
 ### VTK
 
-Files with the "`.vtk`" extension are loaded using [`vtkio`](https://crates.io/crates/vtkio). 
+Legacy VTK files with the "`.vtk`" extension are loaded using [`vtkio`](https://crates.io/crates/vtkio). 
 The VTK file is loaded as a big endian binary file and has to contain an "Unstructured Grid" with either `f32` or `f64` vertex coordinates. 
 Any other data or attributes are ignored except for those attributes that were specified with the ` --interpolate-attributes` command line argument. 
 Currently supported attribute data types are scalar integers, floats and three-component float vectors.
 Only the first "Unstructured Grid" is loaded, other entities are ignored.
 
+Not that currently only the "pure" v4.2 legacy format is supported as documented on [here](https://kitware.github.io/vtk-examples/site/VTKFileFormats/#simple-legacy-formats).
+This corresponds to the `--output-format vtk42` flag of the [`meshio convert`](https://github.com/nschloe/meshio) tool.
+
+### VTU
+
+VTK XML files with the "`.vtu`" extension are loaded using [`vtkio`](https://crates.io/crates/vtkio).
+Currently only VTU files using ASCII or encoded binary are supported.
+Files using "raw" binary sections (i.e. a `<AppendedData encoding="raw">...</AppendedData>` block) are not supported by `vtkio` at the moment.
+
 ### BGEO
 
 Files with the "`.bgeo`" extension are loaded using a custom parser. 
@@ -219,65 +231,77 @@ The file format is inferred from the extension of output filename.
 
 ### The `reconstruct` command
 ```
-splashsurf-reconstruct 0.9.0
-Reconstruct a surface from particle data
-
-USAGE:
-    splashsurf reconstruct [OPTIONS] --cube-size <cube-size> --particle-radius <particle-radius> --smoothing-length <smoothing-length>
-
-FLAGS:
-    -h, --help       Prints help information
-    -V, --version    Prints version information
-
-OPTIONS:
-    -i, --input-file <input-file>
-            Path to the input file where the particle positions are stored (supported formats: VTK, binary f32 XYZ, PLY,
-            BGEO)
-    -s, --input-sequence <input-sequence>
-            Path to a sequence of particle files that should be processed, use `{}` in the filename to indicate a
-            placeholder
-        --output-dir <output-dir>
-            Optional base directory for all output files (default: current working directory)
-
-    -o, --output-file <output-file>
-            Filename for writing the reconstructed surface to disk (default: "{original_filename}_surface.vtk")
-
-        --cube-size <cube-size>
-            The cube edge length used for marching cubes in multiplies of the particle radius, corresponds to the cell
-            size of the implicit background grid
-        --particle-radius <particle-radius>                          The particle radius of the input data
-        --rest-density <rest-density>                                The rest density of the fluid [default: 1000.0]
-        --smoothing-length <smoothing-length>
-            The smoothing length radius used for the SPH kernel, the kernel compact support radius will be twice the
-            smoothing length (in multiplies of the particle radius)
-        --surface-threshold <surface-threshold>
-            The iso-surface threshold for the density, i.e. the normalized value of the reconstructed density level that
-            indicates the fluid surface (in multiplies of the rest density) [default: 0.6]
-        --domain-max <domain-max> <domain-max> <domain-max>
-            Upper corner of the domain where surface reconstruction should be performed, format:domain-
-            max=x_max;y_max;z_max (requires domain-min to be specified)
-        --domain-min <domain-min> <domain-min> <domain-min>
-            Lower corner of the domain where surface reconstruction should be performed, format: domain-
-            min=x_min;y_min;z_min (requires domain-max to be specified)
-    -d, --double-precision=<double-precision>
-            Whether to enable the use of double precision for all computations [default: off]  [possible values: on,
-            Optional filename for writing the point cloud representation of the intermediate density map to disk
-
-        --output-octree <output-octree>
-            Optional filename for writing the octree used to partition the particles to disk
-
-        --interpolate-attributes <interpolate-attributes>...
-            List of point attribute field names from the input file that should be interpolated to the reconstructed
-            surface. Currently this is only supported for VTK input files
-        --normals=<normals>
-            Whether to compute surface normals at the mesh vertices and write them to the output file [default: off]
-            [possible values: on, off]
-        --sph-normals=<sph-normals>
-            Whether to compute the normals using SPH interpolation (smoother and more true to actual fluid surface, but
-            slower) instead of just using area weighted triangle normals [default: on]  [possible values: on, off]
-        --check-mesh=<check-mesh>
-            Whether to check the final mesh for topological problems such as holes (note that when stitching is disabled
-            this will lead to a lot of reported problems) [default: off]  [possible values: on, off]
+splashsurf-reconstruct (v0.9.0) - Reconstruct a surface from particle data
+
+Usage: splashsurf.exe reconstruct [OPTIONS] --particle-radius <PARTICLE_RADIUS> --smoothing-length <SMOOTHING_LENGTH> --cube-size <CUBE_SIZE> <--input-file <INPUT_FILE>|--input-sequence <INPUT_SEQUENCE>>
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+Input/output:
+  -i, --input-file <INPUT_FILE>
+          Path to the input file where the particle positions are stored (supported formats: VTK 4.2, VTU, binary f32 XYZ, PLY, BGEO)
+  -s, --input-sequence <INPUT_SEQUENCE>
+          Path to a sequence of particle files that should be processed, use "{}" in the filename to indicate a placeholder. To specify an output format, use e.g. --output_file="filename_{}.obj"
+  -o, --output-file <OUTPUT_FILE>
+          Filename for writing the reconstructed surface to disk (default: "{original_filename}_surface.vtk")
+      --output-dir <OUTPUT_DIR>
+          Optional base directory for all output files (default: current working directory)
+
+Numerical reconstruction parameters:
+      --particle-radius <PARTICLE_RADIUS>
+          The particle radius of the input data
+      --rest-density <REST_DENSITY>
+          The rest density of the fluid [default: 1000.0]
+      --smoothing-length <SMOOTHING_LENGTH>
+          The smoothing length radius used for the SPH kernel, the kernel compact support radius will be twice the smoothing length (in multiplies of the particle radius)
+      --cube-size <CUBE_SIZE>
+          The cube edge length used for marching cubes in multiplies of the particle radius, corresponds to the cell size of the implicit background grid
+      --surface-threshold <SURFACE_THRESHOLD>
+          The iso-surface threshold for the density, i.e. the normalized value of the reconstructed density level that indicates the fluid surface (in multiplies of the rest density) [default: 0.6]
+      --domain-min <X_MIN> <Y_MIN> <Z_MIN>
+          Lower corner of the domain where surface reconstruction should be performed (requires domain-max to be specified)
+      --domain-max <X_MIN> <Y_MIN> <Z_MIN>
+          Upper corner of the domain where surface reconstruction should be performed (requires domain-min to be specified)
+
+Advanced parameters:
+  -d, --double-precision=<off|on>  Whether to enable the use of double precision for all computations [default: off] [possible values: off, on]
+      --mt-files=<off|on>          Flag to enable multi-threading to process multiple input files in parallel [default: off] [possible values: off, on]
+      --mt-particles=<off|on>      Flag to enable multi-threading for a single input file by processing chunks of particles in parallel [default: on] [possible values: off, on]
+  -n, --num-threads <NUM_THREADS>  Set the number of threads for the worker thread pool
+
+Octree (domain decomposition) parameters:
+      --octree-decomposition=<off|on>
+          Whether to enable spatial decomposition using an octree (faster) instead of a global approach [default: on] [possible values: off, on]
+      --octree-stitch-subdomains=<off|on>
+          Whether to enable stitching of the disconnected local meshes resulting from the reconstruction when spatial decomposition is enabled (slower, but without stitching meshes will not be closed) [default: on] [possible values: off, on]
+      --octree-max-particles <OCTREE_MAX_PARTICLES>
+          The maximum number of particles for leaf nodes of the octree, default is to compute it based on the number of threads and particles
+      --octree-ghost-margin-factor <OCTREE_GHOST_MARGIN_FACTOR>
+          Safety factor applied to the kernel compact support radius when it's used as a margin to collect ghost particles in the leaf nodes when performing the spatial decomposition
+      --octree-global-density=<off|on>
+          Whether to compute particle densities in a global step before domain decomposition (slower) [default: off] [possible values: off, on]
+      --octree-sync-local-density=<off|on>
+          Whether to compute particle densities per subdomain but synchronize densities for ghost-particles (faster, recommended). Note: if both this and global particle density computation is disabled the ghost particle margin has to be increased to at least 2.0 to compute correct density values for ghost particles [default: on] [possible values: off, on]
+
+Interpolation:
+      --normals=<off|on>
+          Whether to compute surface normals at the mesh vertices and write them to the output file [default: off] [possible values: off, on]
+      --sph-normals=<off|on>
+          Whether to compute the normals using SPH interpolation (smoother and more true to actual fluid surface, but slower) instead of just using area weighted triangle normals [default: on] [possible values: off, on]
+      --interpolate-attributes <INTERPOLATE_ATTRIBUTES>
+          List of point attribute field names from the input file that should be interpolated to the reconstructed surface. Currently this is only supported for VTK and VTU input files
+
+Debug options:
+      --output-dm-points <OUTPUT_DM_POINTS>
+          Optional filename for writing the point cloud representation of the intermediate density map to disk
+      --output-dm-grid <OUTPUT_DM_GRID>
+          Optional filename for writing the grid representation of the intermediate density map to disk
+      --output-octree <OUTPUT_OCTREE>
+          Optional filename for writing the octree used to partition the particles to disk
+      --check-mesh=<off|on>
+          Whether to check the final mesh for topological problems such as holes (note that when stitching is disabled this will lead to a lot of reported problems) [default: off] [possible values: off, on]
 ```
 
 ### The `convert` subcommand
@@ -286,32 +310,27 @@ Allows conversion between particle file formats and between mesh file formats. F
 is supported. For meshes only `VTK, PLY -> VTK, OBJ` is supported.
 
 ```
-splashsurf-convert 0.9.0
-Convert particle or mesh files between different file formats
-
-USAGE:
-    splashsurf convert [FLAGS] [OPTIONS] -o <output-file>
-
-FLAGS:
-    -h, --help         Prints help information
-        --overwrite    Whether to overwrite existing files without asking
-    -V, --version      Prints version information
-
-OPTIONS:
-        --domain-max <domain-max> <domain-max> <domain-max>
-            Lower corner of the domain of particles to keep, format:domain-max="x_max;y_max;z_max" (requires domain-min
-            to be specified)
-        --domain-min <domain-min> <domain-min> <domain-min>
-            Lower corner of the domain of particles to keep, format: domain-min="x_min;y_min;z_min" (requires domain-max
-            to be specified)
-        --mesh <input-mesh>
-            Path to the input file with a surface to read (supported formats: .vtk, .ply)
-
-        --particles <input-particles>
-            Path to the input file with particles to read (supported formats: .vtk, .bgeo, .ply, .xyz, .json)
-
-    -o <output-file>
-            Path to the output file (supported formats for particles: .vtk, for meshes: .obj, .vtk)
+splashsurf-convert (v0.9.0) - Convert particle or mesh files between different file formats
+
+Usage: splashsurf.exe convert [OPTIONS] -o <OUTPUT_FILE>
+
+Options:
+      --particles <INPUT_PARTICLES>
+          Path to the input file with particles to read (supported formats: .vtk, .vtu, .bgeo, .ply, .xyz, .json)
+      --mesh <INPUT_MESH>
+          Path to the input file with a surface to read (supported formats: .vtk, .ply)
+  -o <OUTPUT_FILE>
+          Path to the output file (supported formats for particles: .vtk, .bgeo, .json, for meshes: .obj, .vtk)
+      --overwrite
+          Whether to overwrite existing files without asking
+      --domain-min <X_MIN> <Y_MIN> <Z_MIN>
+          Lower corner of the domain of particles to keep (requires domain-max to be specified)
+      --domain-max <X_MIN> <Y_MIN> <Z_MIN>
+          Lower corner of the domain of particles to keep (requires domain-min to be specified)
+  -h, --help
+          Print help
+  -V, --version
+          Print version
 ```
 
 # License
diff --git a/splashsurf/README.md b/splashsurf/README.md
