deprojpy 0.1.0__tar.gz

deprojpy-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, zen-laboratory and mwappner
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

deprojpy-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: deprojpy
+Version: 0.1.0
+Summary: Python behavioral core port of the DeProj MATLAB toolbox
+Author: zen-laboratory, mwappner
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-image>=0.21
+Requires-Dist: pandas>=2.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: tifffile>=2023.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numba>=0.57
+Requires-Dist: labelimage-tools[all]>=0.1.3
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: labels
+Dynamic: license-file
+
+# DeProjPy
+
+`deprojpy` is a Python implementation of the core [matlab project DeProj](https://gitlab.pasteur.fr/iah-public/DeProj) workflow: deproject segmented epithelial cell contours onto a height-map surface, compute 3D cell geometry, and estimate distances on the deprojected surface.
+
+
+The goal is not GUI parity with MATLAB. The focus is a scriptable Python API for deprojection, feature measurement, plotting, and surface-distance calculations.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install deprojpy
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/zen-laboratory/DeProjPy.git
+cd DeProjPy
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The label-image workflow uses the published companion `labelimage-tools`
+package, which is installed automatically with DeProjPy. To install or upgrade
+it explicitly:
+
+```bash
+python -m pip install "labelimage-tools[all]"
+```
+
+## Quick start: DeProj-style mask input
+
+The MATLAB-style workflow starts from a binary-like segmentation mask and a height map. In the mask image, cell interiors are non-zero and cell borders are zero-valued ridges.
+
+```python
+import deprojpy as dp
+
+mask, heightmap = dp.load_tiff_pair("samples/Segmentation-2.tif", "samples/HeightMap-2.tif")
+result = dp.from_heightmap(mask, heightmap,
+    pixel_size=0.183, voxel_depth=1.0, units="µm",
+    invert_z=True, inpaint_zeros=True, prune_zeros=True)
+
+df = result.to_dataframe()
+result.to_csv("measurements.csv")
+```
+
+Returned boundaries, centers, and junction centroids use geometric `(x, y, z)` order in physical units. Input images still use normal image indexing `(row, column)`.
+
+Plot a scalar feature on the deprojected cell polygons:
+
+```python
+fig, ax = dp.plotting.plot_feature_map(result, "area")
+fig, ax = dp.plotting.plot_heightmap_with_centers(heightmap, result)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/examples/output/plots/area_map.png" width="70%">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/examples/output/plots/heightmap_centers.png" width="70%">
+</p>
+
+## Why deproject?
+
+Measurements made directly on the 2D segmentation image can underestimate cell
+geometry when the tissue surface is curved or tilted. DeProjPy measures cell
+contours after lifting them onto the height-map surface, so quantities such as
+area and perimeter are reported in surface-corrected physical units.
+
+A useful diagnostic is the relative area difference between the deprojected
+surface area and the original projected 2D area:
+
+```python
+fig, ax = dp.plotting.plot_relative_error_map(result, 'area')
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/relative_area_error.jpg" width="70%">
+</p>
+
+Positive values indicate cells whose surface-corrected area is larger than their
+projected 2D area. This is the geometric correction DeProj is designed to make
+visible and measurable.
+
+## Alternative input: labeled segmentations
+
+DeProjPy is modernized compared to the Matlab version, as it can also start from an integer label image, where each cell has a unique label and background is zero. This is useful for outputs from segmentation pipelines that already return labels rather than DeProj-style ridge masks, such as [FishFeats](https://gletort.github.io/FishFeats/).
+
+| DeProj-style mask | Label image |
+|---|---|
+| `from_heightmap(mask, heightmap, ...)` | `from_labels(labels, heightmap, ...)` |
+| Cell interiors are non-zero; borders are zero. | All pixels in a cell share a unique integer label; background is zero. |
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/mask_input.png" width="42%">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/labels_input.png" width="42%">
+</p>
+
+```python
+import deprojpy as dp
+
+labels, heightmap = dp.load_label_heightmap_pair("samples/Labels-2.tif", "samples/HeightMap-2.tif")
+result = dp.from_labels(labels, heightmap,
+    pixel_size=0.183, voxel_depth=1.0, units="µm",
+    invert_z=True, inpaint_zeros=True, prune_zeros=True)
+
+df = result.to_dataframe()
+```
+
+The label workflow returns the same kind of `DeprojResult` as the mask workflow. Original label IDs are preserved as `source_label` when available.
+
+## Surface distances
+
+DeProjPy introduces new reusable tools for distances constrained to a surface.
+
+There are two main distance ideas:
+
+- **straight surface distance**: sample the surface along the straight segment in
+  `xy` and measure the lifted 3D polyline;
+- **graph geodesic distance**: build a sparse surface graph and compute shortest
+  paths on the graph. This is an approximation to the continuous geodesic.
+
+For plotting paths on the fitted DeProj cell-contour surface, build the calculator from cell boundaries:
+
+```python
+import numpy as np
+from deprojpy.surface_distance import SurfaceDistanceCalculator, SurfaceGraph
+
+centers = df[["center_x", "center_y"]].to_numpy()
+
+calc = SurfaceDistanceCalculator.from_cell_boundaries(result)
+d_straight = calc.straight_distance(centers[10], centers[200], input_units="physical")
+
+graph = SurfaceGraph.from_calculator(calc, step="auto", connectivity="16")
+d_graph, path_px = graph.distance(centers[10], centers[200],
+    input_units="physical", return_path=True)
+```
+
+For all-pairs straight surface distances between cell centers:
+
+```python
+D = calc.straight_pairwise_distances(centers, input_units="physical")
+```
+
+Graph paths are returned in pixel coordinates, matching graph nodes. To plot them in 3D, sample the calculator surface and convert xy back to physical units:
+
+```python
+path_z = calc.sample_height(path_px, input_units="pixel")
+path_xyz = np.column_stack([path_px * result.pixel_size, path_z])
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/3D_distance.png" width="100%">
+</p>
+
+Use `SurfaceDistanceCalculator.from_result(...)` when you want distances on the prepared height-map surface. Use `SurfaceDistanceCalculator.from_cell_boundaries(...)` when you want paths and distances on the fitted surface represented by the deprojected cell contours.
+
+## What is in a result?
+
+A `DeprojResult` contains:
+
+- `result.epicells`: one `EpiCell` per retained cell;
+- `result.to_dataframe()`: a tabular summary of cell features;
+- `result.prepared_heightmap`: the height map used for deprojection;
+- deprojected boundaries, centers, junctions, and geometry in physical units.
+
+The most common workflow is:
+
+```python
+result = dp.from_heightmap(mask, heightmap, ...)
+df = result.to_dataframe()
+```
+
+or:
+
+```python
+result = dp.from_labels(labels, heightmap, ...)
+df = result.to_dataframe()
+```
+
+## More examples
+
+See [`docs/cookbook.md`](https://github.com/zen-laboratory/DeProjPy/blob/main/docs/cookbook.md) and the scripts in [`examples/`](https://github.com/zen-laboratory/DeProjPy/tree/main/examples) for copy-pastable workflows covering plotting, diagnostics, label inputs, exports, curvature maps, and surface distances.
+
+## Validation status
+
+The Python implementation is tested with synthetic invariants and the original DeProj sample images. It is not yet certified against MATLAB golden outputs.
+
+With the original sample files, expected smoke-check values include:
+
+- image shape `(282, 508)`;
+- 426 retained cells;
+- finite positive cell areas and perimeters.
+
+## License
+
+DeProjPy is distributed under the BSD 3-Clause license. It is partly a Python implementation/port of the core workflow from the original BSD-licensed [MATLAB DeProj project](https://gitlab.pasteur.fr/iah-public/DeProj). This package does not imply endorsement by the original authors or institutions.

deprojpy-0.1.0/README-pypi.md

@@ -0,0 +1,199 @@
+# DeProjPy
+
+`deprojpy` is a Python implementation of the core [matlab project DeProj](https://gitlab.pasteur.fr/iah-public/DeProj) workflow: deproject segmented epithelial cell contours onto a height-map surface, compute 3D cell geometry, and estimate distances on the deprojected surface.
+
+
+The goal is not GUI parity with MATLAB. The focus is a scriptable Python API for deprojection, feature measurement, plotting, and surface-distance calculations.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install deprojpy
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/zen-laboratory/DeProjPy.git
+cd DeProjPy
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The label-image workflow uses the published companion `labelimage-tools`
+package, which is installed automatically with DeProjPy. To install or upgrade
+it explicitly:
+
+```bash
+python -m pip install "labelimage-tools[all]"
+```
+
+## Quick start: DeProj-style mask input
+
+The MATLAB-style workflow starts from a binary-like segmentation mask and a height map. In the mask image, cell interiors are non-zero and cell borders are zero-valued ridges.
+
+```python
+import deprojpy as dp
+
+mask, heightmap = dp.load_tiff_pair("samples/Segmentation-2.tif", "samples/HeightMap-2.tif")
+result = dp.from_heightmap(mask, heightmap,
+    pixel_size=0.183, voxel_depth=1.0, units="µm",
+    invert_z=True, inpaint_zeros=True, prune_zeros=True)
+
+df = result.to_dataframe()
+result.to_csv("measurements.csv")
+```
+
+Returned boundaries, centers, and junction centroids use geometric `(x, y, z)` order in physical units. Input images still use normal image indexing `(row, column)`.
+
+Plot a scalar feature on the deprojected cell polygons:
+
+```python
+fig, ax = dp.plotting.plot_feature_map(result, "area")
+fig, ax = dp.plotting.plot_heightmap_with_centers(heightmap, result)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/examples/output/plots/area_map.png" width="70%">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/examples/output/plots/heightmap_centers.png" width="70%">
+</p>
+
+## Why deproject?
+
+Measurements made directly on the 2D segmentation image can underestimate cell
+geometry when the tissue surface is curved or tilted. DeProjPy measures cell
+contours after lifting them onto the height-map surface, so quantities such as
+area and perimeter are reported in surface-corrected physical units.
+
+A useful diagnostic is the relative area difference between the deprojected
+surface area and the original projected 2D area:
+
+```python
+fig, ax = dp.plotting.plot_relative_error_map(result, 'area')
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/relative_area_error.jpg" width="70%">
+</p>
+
+Positive values indicate cells whose surface-corrected area is larger than their
+projected 2D area. This is the geometric correction DeProj is designed to make
+visible and measurable.
+
+## Alternative input: labeled segmentations
+
+DeProjPy is modernized compared to the Matlab version, as it can also start from an integer label image, where each cell has a unique label and background is zero. This is useful for outputs from segmentation pipelines that already return labels rather than DeProj-style ridge masks, such as [FishFeats](https://gletort.github.io/FishFeats/).
+
+| DeProj-style mask | Label image |
+|---|---|
+| `from_heightmap(mask, heightmap, ...)` | `from_labels(labels, heightmap, ...)` |
+| Cell interiors are non-zero; borders are zero. | All pixels in a cell share a unique integer label; background is zero. |
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/mask_input.png" width="42%">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/labels_input.png" width="42%">
+</p>
+
+```python
+import deprojpy as dp
+
+labels, heightmap = dp.load_label_heightmap_pair("samples/Labels-2.tif", "samples/HeightMap-2.tif")
+result = dp.from_labels(labels, heightmap,
+    pixel_size=0.183, voxel_depth=1.0, units="µm",
+    invert_z=True, inpaint_zeros=True, prune_zeros=True)
+
+df = result.to_dataframe()
+```
+
+The label workflow returns the same kind of `DeprojResult` as the mask workflow. Original label IDs are preserved as `source_label` when available.
+
+## Surface distances
+
+DeProjPy introduces new reusable tools for distances constrained to a surface.
+
+There are two main distance ideas:
+
+- **straight surface distance**: sample the surface along the straight segment in
+  `xy` and measure the lifted 3D polyline;
+- **graph geodesic distance**: build a sparse surface graph and compute shortest
+  paths on the graph. This is an approximation to the continuous geodesic.
+
+For plotting paths on the fitted DeProj cell-contour surface, build the calculator from cell boundaries:
+
+```python
+import numpy as np
+from deprojpy.surface_distance import SurfaceDistanceCalculator, SurfaceGraph
+
+centers = df[["center_x", "center_y"]].to_numpy()
+
+calc = SurfaceDistanceCalculator.from_cell_boundaries(result)
+d_straight = calc.straight_distance(centers[10], centers[200], input_units="physical")
+
+graph = SurfaceGraph.from_calculator(calc, step="auto", connectivity="16")
+d_graph, path_px = graph.distance(centers[10], centers[200],
+    input_units="physical", return_path=True)
+```
+
+For all-pairs straight surface distances between cell centers:
+
+```python
+D = calc.straight_pairwise_distances(centers, input_units="physical")
+```
+
+Graph paths are returned in pixel coordinates, matching graph nodes. To plot them in 3D, sample the calculator surface and convert xy back to physical units:
+
+```python
+path_z = calc.sample_height(path_px, input_units="pixel")
+path_xyz = np.column_stack([path_px * result.pixel_size, path_z])
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zen-laboratory/DeProjPy/main/docs/images/3D_distance.png" width="100%">
+</p>
+
+Use `SurfaceDistanceCalculator.from_result(...)` when you want distances on the prepared height-map surface. Use `SurfaceDistanceCalculator.from_cell_boundaries(...)` when you want paths and distances on the fitted surface represented by the deprojected cell contours.
+
+## What is in a result?
+
+A `DeprojResult` contains:
+
+- `result.epicells`: one `EpiCell` per retained cell;
+- `result.to_dataframe()`: a tabular summary of cell features;
+- `result.prepared_heightmap`: the height map used for deprojection;
+- deprojected boundaries, centers, junctions, and geometry in physical units.
+
+The most common workflow is:
+
+```python
+result = dp.from_heightmap(mask, heightmap, ...)
+df = result.to_dataframe()
+```
+
+or:
+
+```python
+result = dp.from_labels(labels, heightmap, ...)
+df = result.to_dataframe()
+```
+
+## More examples
+
+See [`docs/cookbook.md`](https://github.com/zen-laboratory/DeProjPy/blob/main/docs/cookbook.md) and the scripts in [`examples/`](https://github.com/zen-laboratory/DeProjPy/tree/main/examples) for copy-pastable workflows covering plotting, diagnostics, label inputs, exports, curvature maps, and surface distances.
+
+## Validation status
+
+The Python implementation is tested with synthetic invariants and the original DeProj sample images. It is not yet certified against MATLAB golden outputs.
+
+With the original sample files, expected smoke-check values include:
+
+- image shape `(282, 508)`;
+- 426 retained cells;
+- finite positive cell areas and perimeters.
+
+## License
+
+DeProjPy is distributed under the BSD 3-Clause license. It is partly a Python implementation/port of the core workflow from the original BSD-licensed [MATLAB DeProj project](https://gitlab.pasteur.fr/iah-public/DeProj). This package does not imply endorsement by the original authors or institutions.

deprojpy-0.1.0/README.md

@@ -0,0 +1,199 @@
+# DeProjPy
+
+`deprojpy` is a Python implementation of the core [matlab project DeProj](https://gitlab.pasteur.fr/iah-public/DeProj) workflow: deproject segmented epithelial cell contours onto a height-map surface, compute 3D cell geometry, and estimate distances on the deprojected surface.
+
+
+The goal is not GUI parity with MATLAB. The focus is a scriptable Python API for deprojection, feature measurement, plotting, and surface-distance calculations.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install deprojpy
+```
+
+For development, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/zen-laboratory/DeProjPy.git
+cd DeProjPy
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The label-image workflow uses the published companion `labelimage-tools`
+package, which is installed automatically with DeProjPy. To install or upgrade
+it explicitly:
+
+```bash
+python -m pip install "labelimage-tools[all]"
+```
+
+## Quick start: DeProj-style mask input
+
+The MATLAB-style workflow starts from a binary-like segmentation mask and a height map. In the mask image, cell interiors are non-zero and cell borders are zero-valued ridges.
+
+```python
+import deprojpy as dp
+
+mask, heightmap = dp.load_tiff_pair("samples/Segmentation-2.tif", "samples/HeightMap-2.tif")
+result = dp.from_heightmap(mask, heightmap,
+    pixel_size=0.183, voxel_depth=1.0, units="µm",
+    invert_z=True, inpaint_zeros=True, prune_zeros=True)
+
+df = result.to_dataframe()
+result.to_csv("measurements.csv")
+```
+
+Returned boundaries, centers, and junction centroids use geometric `(x, y, z)` order in physical units. Input images still use normal image indexing `(row, column)`.
+
+Plot a scalar feature on the deprojected cell polygons:
+
+```python
+fig, ax = dp.plotting.plot_feature_map(result, "area")
+fig, ax = dp.plotting.plot_heightmap_with_centers(heightmap, result)
+```
+
+<p align="center">
+  <img src="examples/output/plots/area_map.png" width="70%">
+</p>
+<p align="center">
+  <img src="examples/output/plots/heightmap_centers.png" width="70%">
+</p>
+
+## Why deproject?
+
+Measurements made directly on the 2D segmentation image can underestimate cell
+geometry when the tissue surface is curved or tilted. DeProjPy measures cell
+contours after lifting them onto the height-map surface, so quantities such as
+area and perimeter are reported in surface-corrected physical units.
+
+A useful diagnostic is the relative area difference between the deprojected
+surface area and the original projected 2D area:
+
+```python
+fig, ax = dp.plotting.plot_relative_error_map(result, 'area')
+```
+
+<p align="center">
+  <img src="docs/images/relative_area_error.jpg" width="70%">
+</p>
+
+Positive values indicate cells whose surface-corrected area is larger than their
+projected 2D area. This is the geometric correction DeProj is designed to make
+visible and measurable.
+
+## Alternative input: labeled segmentations
+
+DeProjPy is modernized compared to the Matlab version, as it can also start from an integer label image, where each cell has a unique label and background is zero. This is useful for outputs from segmentation pipelines that already return labels rather than DeProj-style ridge masks, such as [FishFeats](https://gletort.github.io/FishFeats/).
+
+| DeProj-style mask | Label image |
+|---|---|
+| `from_heightmap(mask, heightmap, ...)` | `from_labels(labels, heightmap, ...)` |
+| Cell interiors are non-zero; borders are zero. | All pixels in a cell share a unique integer label; background is zero. |
+
+<p align="center">
+  <img src="docs/images/mask_input.png" width="42%">
+  <img src="docs/images/labels_input.png" width="42%">
+</p>
+
+```python
+import deprojpy as dp
+
+labels, heightmap = dp.load_label_heightmap_pair("samples/Labels-2.tif", "samples/HeightMap-2.tif")
+result = dp.from_labels(labels, heightmap,
+    pixel_size=0.183, voxel_depth=1.0, units="µm",
+    invert_z=True, inpaint_zeros=True, prune_zeros=True)
+
+df = result.to_dataframe()
+```
+
+The label workflow returns the same kind of `DeprojResult` as the mask workflow. Original label IDs are preserved as `source_label` when available.
+
+## Surface distances
+
+DeProjPy introduces new reusable tools for distances constrained to a surface.
+
+There are two main distance ideas:
+
+- **straight surface distance**: sample the surface along the straight segment in
+  `xy` and measure the lifted 3D polyline;
+- **graph geodesic distance**: build a sparse surface graph and compute shortest
+  paths on the graph. This is an approximation to the continuous geodesic.
+
+For plotting paths on the fitted DeProj cell-contour surface, build the calculator from cell boundaries:
+
+```python
+import numpy as np
+from deprojpy.surface_distance import SurfaceDistanceCalculator, SurfaceGraph
+
+centers = df[["center_x", "center_y"]].to_numpy()
+
+calc = SurfaceDistanceCalculator.from_cell_boundaries(result)
+d_straight = calc.straight_distance(centers[10], centers[200], input_units="physical")
+
+graph = SurfaceGraph.from_calculator(calc, step="auto", connectivity="16")
+d_graph, path_px = graph.distance(centers[10], centers[200],
+    input_units="physical", return_path=True)
+```
+
+For all-pairs straight surface distances between cell centers:
+
+```python
+D = calc.straight_pairwise_distances(centers, input_units="physical")
+```
+
+Graph paths are returned in pixel coordinates, matching graph nodes. To plot them in 3D, sample the calculator surface and convert xy back to physical units:
+
+```python
+path_z = calc.sample_height(path_px, input_units="pixel")
+path_xyz = np.column_stack([path_px * result.pixel_size, path_z])
+```
+
+<p align="center">
+  <img src="docs/images/3D_distance.png" width="100%">
+</p>
+
+Use `SurfaceDistanceCalculator.from_result(...)` when you want distances on the prepared height-map surface. Use `SurfaceDistanceCalculator.from_cell_boundaries(...)` when you want paths and distances on the fitted surface represented by the deprojected cell contours.
+
+## What is in a result?
+
+A `DeprojResult` contains:
+
+- `result.epicells`: one `EpiCell` per retained cell;
+- `result.to_dataframe()`: a tabular summary of cell features;
+- `result.prepared_heightmap`: the height map used for deprojection;
+- deprojected boundaries, centers, junctions, and geometry in physical units.
+
+The most common workflow is:
+
+```python
+result = dp.from_heightmap(mask, heightmap, ...)
+df = result.to_dataframe()
+```
+
+or:
+
+```python
+result = dp.from_labels(labels, heightmap, ...)
+df = result.to_dataframe()
+```
+
+## More examples
+
+See [`docs/cookbook.md`](docs/cookbook.md) and the scripts in [`examples/`](examples/) for copy-pastable workflows covering plotting, diagnostics, label inputs, exports, curvature maps, and surface distances.
+
+## Validation status
+
+The Python implementation is tested with synthetic invariants and the original DeProj sample images. It is not yet certified against MATLAB golden outputs.
+
+With the original sample files, expected smoke-check values include:
+
+- image shape `(282, 508)`;
+- 426 retained cells;
+- finite positive cell areas and perimeters.
+
+## License
+
+DeProjPy is distributed under the BSD 3-Clause license. It is a partly Python implementation/port of the core workflow from the original BSD-licensed [MATLAB DeProj project](https://gitlab.pasteur.fr/iah-public/DeProj). This package does not imply endorsement by the original authors or institutions.