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

dict

pyrockfall._filesystem.writeMaterials(filepath: str, materials: dict[int, Material])[source]

Writes material parameters to a CSV file.

Parameters:
  • filepath (str) – Path to the output CSV file.

  • materials (dict) – Dictionary mapping material_id to Material instances.

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:

dict[str, np.ndarray]

Raises:
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.exportDistribution(var)[source]
pyrockfall._filesystem.exportSlope(filepath: str, slope: Slope)[source]
pyrockfall._filesystem.importSlope(filepath: str, materials: List[Material]) → Slope[source]
pyrockfall._filesystem.exportSeeders(filepath: str, seeders: List[Seeder], rockTypes: List[Rock])[source]
pyrockfall._filesystem.importSeeders(filepath: str, rockTypes: List[Rock]) → List[Seeder][source]
pyrockfall._filesystem.exportMaterials(filepath: str, materials: List[Material], colors: List[Tuple[int, int, int]] | None = None)[source]
pyrockfall._filesystem.importMaterials(filepath: str) → List[Material][source]
pyrockfall._filesystem.exportRocks(filepath: str, rocks: List[Rock], colors: List[tuple[int, int, int]] | None = None)[source]
pyrockfall._filesystem.importRocks(filepath: str) → List[Rock][source]
pyrockfall._filesystem.exportSettings(filepath: str, analysis: Analysis)[source]
pyrockfall._filesystem.importSettings(filepath: str) → Analysis[source]