depth2normal 1.0.0__py3-none-any.whl

depth2normal/__init__.py

@@ -0,0 +1,6 @@
+"""depth2normal -- convert depth maps to normal maps."""
+
+from depth2normal.converter import METHODS, convert, depth_to_normal, load_depth
+
+__version__ = "1.0.0"
+__all__ = ["METHODS", "convert", "depth_to_normal", "load_depth", "__version__"]

depth2normal/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m depth2normal`` when the package is importable."""
+
+from depth2normal.cli import cli
+
+if __name__ == "__main__":
+    cli()

depth2normal/cli.py

@@ -0,0 +1,52 @@
+"""Command-line interface for depth2normal."""
+
+from __future__ import annotations
+
+import click
+
+from depth2normal.converter import METHODS, convert
+
+
+@click.command()
+@click.argument("input_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "-o",
+    "--output",
+    default="normal_map.png",
+    show_default=True,
+    help="Output path for the generated normal map.",
+)
+@click.option(
+    "-s",
+    "--strength",
+    default=1.0,
+    show_default=True,
+    type=float,
+    help="Gradient multiplier controlling normal intensity.",
+)
+@click.option(
+    "-m",
+    "--method",
+    default="gaussian",
+    show_default=True,
+    type=click.Choice(METHODS, case_sensitive=False),
+    help="Gradient algorithm.",
+)
+@click.option(
+    "--sigma",
+    default=1.0,
+    show_default=True,
+    type=float,
+    help="Gaussian kernel sigma (only for --method gaussian).",
+)
+@click.version_option(package_name="depth2normal")
+def cli(
+    input_path: str,
+    output: str,
+    strength: float,
+    method: str,
+    sigma: float,
+) -> None:
+    """Convert a depth map image to a normal map image."""
+    convert(input_path, output, strength=strength, method=method, sigma=sigma)
+    click.echo(f"Normal map saved to {output}")

depth2normal/converter.py

@@ -0,0 +1,124 @@
+"""Core depth-to-normal-map conversion logic."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+from PIL import Image
+from scipy.ndimage import correlate, gaussian_filter, sobel
+
+METHODS = ("gaussian", "sobel", "scharr")
+Method = Literal["gaussian", "sobel", "scharr"]
+
+_SCHARR_X = np.array([[-3, 0, 3], [-10, 0, 10], [-3, 0, 3]], dtype=np.float64)
+_SCHARR_Y = _SCHARR_X.T
+
+
+def _gradients_sobel(depth: NDArray[np.float64]) -> tuple[NDArray, NDArray]:
+    return sobel(depth, axis=1), sobel(depth, axis=0)
+
+
+def _gradients_scharr(depth: NDArray[np.float64]) -> tuple[NDArray, NDArray]:
+    return correlate(depth, _SCHARR_X), correlate(depth, _SCHARR_Y)
+
+
+def _gradients_gaussian(
+    depth: NDArray[np.float64],
+    sigma: float,
+) -> tuple[NDArray, NDArray]:
+    dx = gaussian_filter(depth, sigma=sigma, order=[0, 1])
+    dy = gaussian_filter(depth, sigma=sigma, order=[1, 0])
+    return dx, dy
+
+
+def depth_to_normal(
+    depth: NDArray[np.floating],
+    strength: float = 1.0,
+    method: Method = "gaussian",
+    sigma: float = 1.0,
+) -> NDArray[np.uint8]:
+    """Convert a 2-D depth array to an RGB normal map.
+
+    Args:
+        depth: Grayscale depth image as a 2-D float array.  Gradients are
+            computed on the raw values so that the original pixel range
+            (e.g. 0-255) drives the normal intensity.
+        strength: Multiplier applied to the surface gradients.  Higher
+            values produce more pronounced normals.
+        method: Gradient algorithm -- ``"gaussian"`` (smooth, best quality),
+            ``"sobel"`` (fast, sharp), or ``"scharr"`` (better rotational
+            accuracy than Sobel).
+        sigma: Standard deviation for the Gaussian derivative kernel.
+            Higher values produce smoother normals at the cost of fine
+            detail.  Only used when *method* is ``"gaussian"``.
+
+    Returns:
+        An (H, W, 3) uint8 RGB array where each pixel encodes the
+        surface normal mapped to the [0, 255] range.
+
+    Raises:
+        ValueError: If *depth* is not 2-D or *method* is unknown.
+    """
+    if depth.ndim != 2:
+        raise ValueError(f"Expected a 2-D depth array, got shape {depth.shape}")
+    if method not in METHODS:
+        raise ValueError(f"Unknown method {method!r}, choose from {METHODS}")
+
+    depth = depth.astype(np.float64)
+
+    if method == "gaussian":
+        dx, dy = _gradients_gaussian(depth, sigma)
+    elif method == "scharr":
+        dx, dy = _gradients_scharr(depth)
+    else:
+        dx, dy = _gradients_sobel(depth)
+
+    dx *= strength
+    dy *= strength
+
+    normal = np.dstack((-dx, -dy, np.ones_like(dx)))
+
+    norm = np.linalg.norm(normal, axis=2, keepdims=True)
+    norm = np.where(norm == 0, 1, norm)
+    normal = normal / norm
+
+    normal_uint8 = ((normal + 1) * 0.5 * 255).clip(0, 255).astype(np.uint8)
+    return normal_uint8
+
+
+def load_depth(path: str | Path) -> NDArray[np.floating]:
+    """Load an image file as a 2-D float64 depth array.
+
+    Preserve native single-channel grayscale depth formats such as 8-bit,
+    16-bit, and floating-point images. Multichannel images are converted
+    to grayscale.
+    """
+    with Image.open(path) as img:
+        if len(img.getbands()) != 1 or img.mode == "P":
+            img = img.convert("L")
+        return np.asarray(img, dtype=np.float64)
+
+
+def convert(
+    input_path: str | Path,
+    output_path: str | Path = "normal_map.png",
+    strength: float = 1.0,
+    method: Method = "gaussian",
+    sigma: float = 1.0,
+) -> None:
+    """Convert a depth map image file to a normal map image file.
+
+    Args:
+        input_path: Path to the source depth map image.
+        output_path: Destination path for the generated normal map.
+            Defaults to ``"normal_map.png"``.
+        strength: Gradient multiplier (see :func:`depth_to_normal`).
+        method: Gradient algorithm (see :func:`depth_to_normal`).
+        sigma: Gaussian sigma (see :func:`depth_to_normal`).
+    """
+    depth = load_depth(input_path)
+    normal = depth_to_normal(depth, strength=strength, method=method, sigma=sigma)
+    Image.fromarray(normal, mode="RGB").save(output_path)

depth2normal-1.0.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: depth2normal
+Version: 1.0.0
+Summary: Convert depth map images to normal map images
+Project-URL: Homepage, https://github.com/cobanov/depth2normal
+Project-URL: Repository, https://github.com/cobanov/depth2normal
+Project-URL: Issues, https://github.com/cobanov/depth2normal/issues
+Author: Mert Cobanov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d,computer-vision,depth-map,image-processing,normal-map
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# depth2normal
+
+Convert depth map images to RGB normal maps for shading and 3D workflows.
+
+**Requirements:** Python 3.10 or newer. Runtime dependencies are NumPy, SciPy, Pillow, and Click (no OpenCV).
+
+| Depth (input) | Normal map (output) |
+| --- | --- |
+| ![Depth example](https://raw.githubusercontent.com/cobanov/depth2normal/main/assets/depth.png) | ![Normal map example](https://raw.githubusercontent.com/cobanov/depth2normal/main/assets/normal.png) |
+
+## Install
+
+**From PyPI** (after you publish the package):
+
+```bash
+pip install depth2normal
+```
+
+With uv in **another** project (not this repository):
+
+```bash
+uv add depth2normal
+```
+
+Or without editing that project’s `pyproject.toml`:
+
+```bash
+uv pip install depth2normal
+```
+
+> **Note:** Inside this repository, do **not** run `uv add depth2normal`—the project name matches the package name, and uv blocks that self-dependency. Use `uv sync` instead (see below).
+
+## Usage
+
+All CLI forms share the same options (see table at the end of this section).
+
+### After `pip install` or `uv pip install`
+
+```bash
+depth2normal path/to/depth.png -o normal.png
+```
+
+### From a clone (recommended for development)
+
+Install the project and dev tools, then use the console script or the helper script:
+
+```bash
+git clone https://github.com/cobanov/depth2normal.git
+cd depth2normal
+uv sync
+```
+
+```bash
+uv run depth2normal assets/depth.png -o normal.png
+```
+
+Or run the repo-root helper without an editable install (still uses deps from `uv sync`):
+
+```bash
+uv run run.py assets/depth.png -o normal.png
+```
+
+With plain `python` (dependencies must be available in that environment, e.g. after `pip install -e .`):
+
+```bash
+python run.py assets/depth.png -o normal.png
+```
+
+Module entry point when `src` is on `PYTHONPATH` or the package is installed:
+
+```bash
+PYTHONPATH=src python -m depth2normal assets/depth.png -o normal.png
+```
+
+### Python API
+
+```python
+import depth2normal
+
+depth2normal.convert("depth.png", "normal.png")
+depth2normal.convert("depth.png", "normal.png", strength=2.0, method="gaussian", sigma=1.5)
+
+import numpy as np
+
+depth_array = np.load("depth.npy")
+normal_map = depth2normal.depth_to_normal(depth_array, method="scharr")
+```
+
+### CLI options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-o`, `--output` | `normal_map.png` | Output image path |
+| `-s`, `--strength` | `1.0` | Scales gradients (stronger = more pronounced normals) |
+| `-m`, `--method` | `gaussian` | Gradient algorithm: `gaussian`, `sobel`, or `scharr` |
+| `--sigma` | `1.0` | Gaussian kernel width (only with `--method gaussian`) |
+| `--version` | — | Print version and exit |
+
+Positional argument: path to the depth image file.
+
+### Gradient methods
+
+| Method | Quality | Speed | Notes |
+| --- | --- | --- | --- |
+| `gaussian` | Best | Moderate | Smooth normals via Gaussian derivative. `--sigma` controls the smoothness/detail tradeoff. |
+| `sobel` | Good | Fast | Classic 3x3 Sobel. Sharp but can show staircase artifacts on quantized depth. |
+| `scharr` | Good | Fast | Better rotational accuracy than Sobel, similar speed. |
+
+## How it works
+
+1. Load depth as grayscale float array.
+2. Estimate surface gradients with the selected filter (Gaussian derivative, Sobel, or Scharr).
+3. Build normals (-dx, -dy, 1), normalize to unit length, then map to 8-bit RGB.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+MIT

depth2normal-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+depth2normal/__init__.py,sha256=Y-4gKbMxh29xFWpPBhRCD7vgPrJOgNVJApZJoK6q3YQ,243
+depth2normal/__main__.py,sha256=1fpfd09B5DBUYn3RSKaGkXxXlhWn2HylVVKOzvjemWU,143
+depth2normal/cli.py,sha256=RCJv0W3s_Q7u6coagh3xFJLhuS86mjXDDpKvzBvmB2U,1237
+depth2normal/converter.py,sha256=zfG5NsWAgbzvrO7fPWK3lnYGc9JGEu1kGBP_MScctOI,4205
+depth2normal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+depth2normal-1.0.0.dist-info/METADATA,sha256=9p5f8RQ9X33AVkPMq7pV2lBydxhKM07h6sfaFkva3qw,4670
+depth2normal-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+depth2normal-1.0.0.dist-info/entry_points.txt,sha256=hZ6GRQLuHHy-FhODbq7yehuwphMeGwDnAkK-sortbJM,54
+depth2normal-1.0.0.dist-info/licenses/LICENSE,sha256=oYV_s8A1IS_T54BCvvcrI1qhyXji1eN_Yz2_UHbmru8,1069
+depth2normal-1.0.0.dist-info/RECORD,,

depth2normal-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

depth2normal-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+depth2normal = depth2normal.cli:cli

depth2normal-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mert Cobanov
+
+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.