_filesystem module¶
Filesystem utilities for pyrockfall¶
Provides functions for reading and writing material and configuration files used by the pyrockfall package.
This module is responsible for handling CSV and other file formats that define material properties, distribution parameters, and simulation inputs.
- Key features:
Reading material parameter files and constructing random variable objects.
Writing/exporting parameter data for reproducibility and sharing.
Designed to support core pyrockfall workflows.
This module should remain general to facilitate easy extension and maintenance as the pyrockfall project evolves.
- pyrockfall._filesystem.readMaterials(filepath)[source]¶
Reads a CSV file defining material parameters and constructs random variables for normal restitution, tangential restitution, and friction angle for each material.
- The function expects the CSV to have, for each material:
name: Material name.
- For each property (Rn, Rt, phi):
<Property>_id: Distribution type as integer (see stats.DistributionID enum).
<Property>_mean: Target mean of the truncated distribution.
<Property>_std: Target standard deviation of the truncated distribution.
<Property>_min: Lower bound of support.
<Property>_max: Upper bound of support.
- Parameters:
filepath (str) – Path to the CSV file.
- Returns:
- Material instances, with the following attributes set:
normalRestitution: Random variable for normal restitution (rn)
tangentialRestitution: Random variable for tangential restitution (rt)
frictionAngle: Random variable for friction angle (phi)
- Return type:
- pyrockfall._filesystem.writeMaterials(filepath: str, materials: dict[int, Material])[source]¶
Writes material parameters to a CSV file.
- pyrockfall._filesystem.read_property(filename: str, property_name: str)[source]¶
Read a scalar or vector property from a point set file.
- Supported:
.ply (ASCII, binary little-endian, binary big-endian) [native]
.npz (keys become properties) [native]
.pcd, .xyz (and .ply fallback) via lazy Open3D if available
- Vector auto-detection:
exact groups: xyz, normal(n: nx,ny,nz or normal_x,…) ; rgb/rgba ; uv
generic: <name>_{x,y,z} or <name>{x,y,z}
- Returns:
data (np.ndarray) – (N,) for scalar or (N, k) for vectors.
meta (dict) – {“is_vector”: bool, “components”: [names…]}
- pyrockfall._filesystem.read_properties(filename: str, required: list[str]) dict[str, ndarray][source]¶
Read properties from a geometry file and return them.
- Parameters:
filename – Path to the file (.npz, .ply, .pcd, .xyz, .obj, .stl, .off).
required – List of attributes to read (e.g. [“points”, “normals”]).
- Returns:
Mapping from attribute name to array.
- Return type:
- Raises:
FileNotFoundError – If file does not exist.
ValueError – If a required attribute is missing or unsupported.
- pyrockfall._filesystem.write_ply_with_attrs(filename: str, core: Mapping[str, ndarray], attrs: Mapping[str, ndarray], *, comments: dict[str, str] | None)[source]¶
PLY writer using plyfile, supporting arbitrary per-vertex attributes.
- pyrockfall._filesystem.write_npz_full_fidelity(filename: str, core: Mapping[str, ndarray], attrs: Mapping[str, ndarray])[source]¶
Store everything exactly: core dict + all attributes (including per-triangle).
- pyrockfall._filesystem.write_xyz_ascii(filename: str, core: Mapping[str, ndarray], attrs: Mapping[str, ndarray], *, allow_lossy: bool)[source]¶
Very simple ASCII XYZ(+ extras). CloudCompare can import and you can map columns to SFs, but there is no header to name fields. Prefer PLY.
- pyrockfall._filesystem.write_pcd_minimal(filename: str, core: Mapping[str, ndarray], attrs: Mapping[str, ndarray], *, allow_lossy: bool)[source]¶
Minimal PCD writer (xyz + optional rgb). For anything richer, prefer PLY.
- pyrockfall._filesystem.exportSeeders(filepath: str, seeders: List[Seeder], rockTypes: List[Rock])[source]¶
- pyrockfall._filesystem.exportMaterials(filepath: str, materials: List[Material], colors: List[Tuple[int, int, int]] | None = None)[source]¶