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.
