svr-roughness 0.3.0__tar.gz

svr_roughness-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HAM Lab, Iowa State University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

svr_roughness-0.3.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: svr-roughness
+Version: 0.3.0
+Summary: Surface roughness metrics from scanner point clouds
+Author: Sullivan Hart, HAM Lab, Iowa State University
+License: MIT License
+        
+        Copyright (c) 2026 HAM Lab, Iowa State University
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Keywords: roughness,point-cloud,ply,surface-metrology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: scipy>=1.10
+Dynamic: license-file
+
+# svr-roughness
+
+`svr-roughness` is a reusable Python library for SurfInspect-compatible surface
+roughness analysis from industrial scan outputs. Use `svr_roughness` as the
+consistent Python import name.
+
+The core API is file-type agnostic: roughness is computed from an `Nx3` NumPy-like XYZ point array in millimeters. Svr is calculated from signed distances to a smoothed, triangulated reference surface and a KD-tree variogram modeled on SurfInspect. The regular grid remains available for Sa/Sq and visualization. Reference mesh resolution and smoothing default to 0.30 mm, matching the supplied SurfInspect A2 reference closely. At most 10,000 variogram points are used by default to bound memory on industrial scans; set `max_svr_points` higher when full point coverage is required.
+
+```python
+config = RoughnessConfig(
+    mesh_resolution_mm=0.30,
+    mesh_smoothing_mm=0.30,
+    svr_points=10,
+    svr_span_mm=0.50,
+)
+```
+
+## Install
+
+From this repository:
+
+```bash
+python -m pip install ./svr-roughness
+```
+
+For deployment from inside `SurfaceRoughnessPi`:
+
+```bash
+python -m pip install ../svr-roughness
+```
+
+## Python API
+
+Use `analyze_points()` when your scanner or upstream software already gives you XYZ points:
+
+```python
+import numpy as np
+from svr_roughness import analyze_points
+
+points_xyz_mm = np.asarray(points)  # shape (N, 3), columns x/y/z, units mm
+result = analyze_points(points_xyz_mm, grid_mm=0.30, short_cutoff_mm=0.6, long_cutoff_mm=8.0)
+
+print(result.sa_um, result.sq_um, result.svr_um)
+```
+
+Use `analyze_file()` as a convenience adapter for supported files:
+
+```python
+from svr_roughness import RoughnessConfig, analyze_file
+
+config = RoughnessConfig(grid_mm=0.30, short_cutoff_mm=0.6, long_cutoff_mm=8.0)
+result = analyze_file("scan.ply", config=config)
+```
+
+Supported file loaders (all are converted to an `Nx3` NumPy array):
+
+- ASCII and binary little-endian `.ply` point clouds
+- ASCII and binary `.pcd` point clouds
+- ASCII and binary `.stl` mesh vertices
+- `.obj` vertex meshes
+- comma-, tab-, or whitespace-delimited `.csv`, `.tsv`, `.xyz`, and `.txt`
+- `.npy` and `.npz` NumPy arrays
+
+STL files are converted to their unique mesh vertices before analysis. For production mesh metrology, prefer scanner point clouds or add controlled surface sampling before calling `analyze_points()`.
+
+## Result Output
+
+```python
+result.save_grid_npz("output/roughness/latest_grid.npz")
+result.save_metrics_json("output/roughness/latest_metrics.json")
+```
+
+`save_metrics_json()` writes:
+
+- `sa_um`
+- `sq_um`
+- `svr_um`
+- point counts, grid dimensions, grid coverage, and filter cutoffs
+
+`save_grid_npz()` writes:
+
+- `grid_raw`
+- `grid_filled`
+- `grid_filtered`
+- `valid_raw`
+- `valid_filled`
+- `grid_origin`
+- plane basis arrays
+
+## Command line
+
+The package also includes a no-code command for scanner integrations:
+
+```bash
+svr-roughness scan.ply --grid-mm 0.30 --metrics-out metrics.json --grid-out grid.npz
+```
+
+Coordinates are assumed to be millimeters, and metrics are reported in
+micrometers. Unit conversion should happen before calling the library.

svr_roughness-0.3.0/README.md

@@ -0,0 +1,99 @@
+# svr-roughness
+
+`svr-roughness` is a reusable Python library for SurfInspect-compatible surface
+roughness analysis from industrial scan outputs. Use `svr_roughness` as the
+consistent Python import name.
+
+The core API is file-type agnostic: roughness is computed from an `Nx3` NumPy-like XYZ point array in millimeters. Svr is calculated from signed distances to a smoothed, triangulated reference surface and a KD-tree variogram modeled on SurfInspect. The regular grid remains available for Sa/Sq and visualization. Reference mesh resolution and smoothing default to 0.30 mm, matching the supplied SurfInspect A2 reference closely. At most 10,000 variogram points are used by default to bound memory on industrial scans; set `max_svr_points` higher when full point coverage is required.
+
+```python
+config = RoughnessConfig(
+    mesh_resolution_mm=0.30,
+    mesh_smoothing_mm=0.30,
+    svr_points=10,
+    svr_span_mm=0.50,
+)
+```
+
+## Install
+
+From this repository:
+
+```bash
+python -m pip install ./svr-roughness
+```
+
+For deployment from inside `SurfaceRoughnessPi`:
+
+```bash
+python -m pip install ../svr-roughness
+```
+
+## Python API
+
+Use `analyze_points()` when your scanner or upstream software already gives you XYZ points:
+
+```python
+import numpy as np
+from svr_roughness import analyze_points
+
+points_xyz_mm = np.asarray(points)  # shape (N, 3), columns x/y/z, units mm
+result = analyze_points(points_xyz_mm, grid_mm=0.30, short_cutoff_mm=0.6, long_cutoff_mm=8.0)
+
+print(result.sa_um, result.sq_um, result.svr_um)
+```
+
+Use `analyze_file()` as a convenience adapter for supported files:
+
+```python
+from svr_roughness import RoughnessConfig, analyze_file
+
+config = RoughnessConfig(grid_mm=0.30, short_cutoff_mm=0.6, long_cutoff_mm=8.0)
+result = analyze_file("scan.ply", config=config)
+```
+
+Supported file loaders (all are converted to an `Nx3` NumPy array):
+
+- ASCII and binary little-endian `.ply` point clouds
+- ASCII and binary `.pcd` point clouds
+- ASCII and binary `.stl` mesh vertices
+- `.obj` vertex meshes
+- comma-, tab-, or whitespace-delimited `.csv`, `.tsv`, `.xyz`, and `.txt`
+- `.npy` and `.npz` NumPy arrays
+
+STL files are converted to their unique mesh vertices before analysis. For production mesh metrology, prefer scanner point clouds or add controlled surface sampling before calling `analyze_points()`.
+
+## Result Output
+
+```python
+result.save_grid_npz("output/roughness/latest_grid.npz")
+result.save_metrics_json("output/roughness/latest_metrics.json")
+```
+
+`save_metrics_json()` writes:
+
+- `sa_um`
+- `sq_um`
+- `svr_um`
+- point counts, grid dimensions, grid coverage, and filter cutoffs
+
+`save_grid_npz()` writes:
+
+- `grid_raw`
+- `grid_filled`
+- `grid_filtered`
+- `valid_raw`
+- `valid_filled`
+- `grid_origin`
+- plane basis arrays
+
+## Command line
+
+The package also includes a no-code command for scanner integrations:
+
+```bash
+svr-roughness scan.ply --grid-mm 0.30 --metrics-out metrics.json --grid-out grid.npz
+```
+
+Coordinates are assumed to be millimeters, and metrics are reported in
+micrometers. Unit conversion should happen before calling the library.

svr_roughness-0.3.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "svr-roughness"
+version = "0.3.0"
+description = "Surface roughness metrics from scanner point clouds"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Sullivan Hart" },
+  { name = "HAM Lab, Iowa State University" }
+]
+dependencies = [
+  "numpy>=1.24",
+  "opencv-python-headless>=4.8",
+  "scipy>=1.10"
+]
+keywords = ["roughness", "point-cloud", "ply", "surface-metrology"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering"
+]
+
+[project.scripts]
+svr-roughness = "svr_roughness.__main__:main"
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+svr_roughness = ["py.typed"]

svr_roughness-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

svr_roughness-0.3.0/src/svr_roughness/__init__.py

@@ -0,0 +1,35 @@
+"""Surface roughness analysis for scanner point clouds."""
+
+from .analyze import (
+    analyze_file,
+    analyze_ply,
+    analyze_points,
+    compute_roughness,
+    compute_roughness_from_ply,
+)
+from .config import RoughnessConfig
+from .io import load_ascii_ply, load_delimited, load_obj, load_pcd, load_ply, load_points, load_stl_vertices
+from .result import PlaneFit, RoughnessGrid, RoughnessResult, format_report
+from ._algorithm import svr_map, svr_surface
+
+__all__ = [
+    "PlaneFit",
+    "RoughnessConfig",
+    "RoughnessGrid",
+    "RoughnessResult",
+    "analyze_file",
+    "analyze_ply",
+    "analyze_points",
+    "compute_roughness",
+    "compute_roughness_from_ply",
+    "format_report",
+    "load_ascii_ply",
+    "load_delimited",
+    "load_obj",
+    "load_pcd",
+    "load_ply",
+    "load_points",
+    "load_stl_vertices",
+    "svr_map",
+    "svr_surface",
+]

svr_roughness-0.3.0/src/svr_roughness/__main__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .analyze import analyze_file
+from .config import RoughnessConfig
+from .result import format_report
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Calculate surface roughness from a point-cloud file.")
+    parser.add_argument("input", type=Path, help="Input PLY, PCD, STL, OBJ, CSV, XYZ, TXT, TSV, NPY, or NPZ file")
+    parser.add_argument("--grid-mm", type=float, default=0.30)
+    parser.add_argument("--short-cutoff-mm", type=float, default=0.0)
+    parser.add_argument("--long-cutoff-mm", type=float, default=0.0)
+    parser.add_argument("--metrics-out", type=Path)
+    parser.add_argument("--grid-out", type=Path)
+    args = parser.parse_args()
+
+    result = analyze_file(
+        args.input,
+        RoughnessConfig(
+            grid_mm=args.grid_mm,
+            short_cutoff_mm=args.short_cutoff_mm,
+            long_cutoff_mm=args.long_cutoff_mm,
+        ),
+    )
+    print(format_report(result))
+    if args.metrics_out:
+        result.save_metrics_json(args.metrics_out)
+    if args.grid_out:
+        result.save_grid_npz(args.grid_out)
+
+
+if __name__ == "__main__":
+    main()