readme.md file for pFlowToVTK

utilities/pFlowToVTK/README.md

@@ -0,0 +1,110 @@
+# pFlowToVTK Utility
+
+## Overview
+
+pFlowToVTK is a utility for converting phasicFlow simulation data into VTK (Visualization Toolkit) file format. This enables visualization of simulation results in applications like ParaView. The utility handles two primary types of data:
+
+1. **Particle Data** (pointField) - Converts particle properties such as position, velocity, forces, etc.
+2. **Geometry Data** (triSurfaceField) - Converts surface geometries and their properties
+
+## Basic Usage
+
+```bash
+pFlowToVTK [OPTIONS]
+```
+
+After simulation is complete, run this command from the case directory to convert all simulation data to VTK format, which will be stored in the `./VTK/` folder.
+
+## Command Line Options
+
+| Option | Description |
+|--------|-------------|
+| `--no-geometry` | Skip conversion of geometry data to VTK format |
+| `--no-particles` | Skip conversion of particle data to VTK format |
+| `-b, --binary` | Write VTK files in binary format (default is ASCII). Using binary format accelerates conversion (5-10x) and visualization in ParaView |
+| `-o, --out-folder <path>` | Specify the output directory path (default: `./VTK/`) |
+| `-s, --separate-surfaces` | Create separate files for each sub-surface in geometry |
+| `-f, --fields <field1> <field2>...` | Specify which particle fields to convert (space-separated list). If not specified, all fields are converted |
+| `-t, --time <times>` | Process only specific time folders. Accepts multiple formats: <br> - Space-separated list of times (e.g., `0.1 0.2 0.3`) <br> - Strided range with format `<begin>:<stride>:<end>` (e.g., `0.1:0.1:0.5`) <br> - Interval with format `<begin>:<end>` (e.g., `0.1:0.5`) |
+| `-h, --help` | Display help message with all available options |
+
+## Examples
+
+Convert all data with default settings:
+
+```bash
+pFlowToVTK
+```
+
+Convert only geometry data:
+
+```bash
+pFlowToVTK --no-particles
+```
+
+Convert only particle data in binary format:
+
+```bash
+pFlowToVTK --no-geometry --binary
+```
+
+Convert specific fields for particles:
+
+```bash
+pFlowToVTK -f velocity diameter contactForce
+```
+
+Convert data for specific time steps:
+
+```bash
+pFlowToVTK -t 0.1 0.2 0.3
+```
+
+Convert data for a range of time steps:
+
+```bash
+pFlowToVTK -t 0.1:0.1:1.0
+```
+
+Write output to a custom directory:
+
+```bash
+pFlowToVTK -o /path/to/custom/output
+```
+
+## Output Structure
+
+The utility creates the following directory structure:
+```
+simulationCase/
+├── 0/              # Contains the initial time step data
+├── 0.1/            # time-folder for simulation data at 0.1 s
+├── 0.2/            # time-folder for simulation data at 0.2 s
+├── caseSetup/      # Contains the case setup files
+├── settings/       # Contains the settings files
+└── VTK/
+    ├── geometry/           # Contains VTK files for geometry
+    │   └── surface-*.vtk   # Geometry at different time steps
+    └── particles/          # Contains VTK files for particles
+        └── particles-*.vtk # Particle data at different time steps
+```
+
+Additionally, the utility generates `.vtk.series` files in the VTK root folder, which can be used by ParaView for loading time series data automatically:
+```
+VTK/
+├── particles.vtk.series
+└── surface.vtk.series  # (and possibly other surface names if --separate-surfaces is used)
+```
+
+## Recommendations
+
+- Use binary format (`-b` flag) for large simulations to significantly improve conversion speed and reduce file size
+- For complex geometries with multiple sub-surfaces, consider using `-s` flag to keep surfaces in separate files for better visualization
+- When working with large datasets, use the `-t` option to convert only the time steps you need to visualize
+
+## See Also
+## Related Utilities
+- [`tutorials`](../../tutorials): Contains example cases and step-by-step guides for using phasicFlow
+- [`particlesPhasicFlow`](../particlesPhasicFlow): Creates the initial fields for particles
+- [`geometryPhasicFlow`](../geometryPhasicFlow): Creates the geometry
+- [`postprocessPhasicFlow`](../postprocessPhasicFlow): Tool for performing various cell-based averaging on fields