euler-preprocess 1.0.1__tar.gz

euler_preprocess-1.0.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: euler-preprocess
+Version: 1.0.1
+Summary: Physics-based preprocessing (fog, etc.) for RGB+depth datasets
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: Pillow
+Requires-Dist: euler-loading
+Provides-Extra: gpu
+Requires-Dist: torch; extra == "gpu"
+Provides-Extra: progress
+Requires-Dist: tqdm; extra == "progress"
+
+# euler-preprocess
+
+Physics-based preprocessing transforms for multi-modal RGB+depth datasets. Built on top of [euler-loading](https://github.com/d-rothen/euler-loading) and [ds-crawler](https://github.com/d-rothen/ds-crawler).
+
+Available transforms:
+
+| Command | Description |
+|---|---|
+| `euler-preprocess fog` | Synthetic fog via the Koschmieder atmospheric scattering model |
+| `euler-preprocess sky-depth` | Override depth values in sky regions with a constant |
+| `euler-preprocess radial` | Convert planar (z-buffer) depth to radial (Euclidean) depth |
+
+## Installation
+
+```bash
+uv pip install "euler-preprocess[gpu,progress] @ git+https://github.com/d-rothen/euler-fog"
+```
+
+## Usage
+
+```bash
+euler-preprocess fog       -c configs/example_dataset_config.json
+euler-preprocess sky-depth -c configs/sky_depth_dataset_config.json
+euler-preprocess radial    -c configs/radial_dataset_config.json
+```
+
+## Configuration
+
+Every subcommand takes a **dataset config** JSON that points to the input data and a **transform config**. Each modality path must be a directory indexed by [ds-crawler](https://github.com/d-rothen/ds-crawler) with an `euler_loading` property that specifies the loader and function. This allows euler-loading to auto-select the correct dataset-specific loader.
+
+### Dataset Config
+
+```json
+{
+  "transform_config_path": "configs/run1.json",
+  "output_path": "/path/to/output",
+  "modalities": {
+    "rgb": "/path/to/rgb",
+    "depth": "/path/to/depth",
+    "semantic_segmentation": "/path/to/classSegmentation"
+  },
+  "hierarchical_modalities": {
+    "intrinsics": "/path/to/intrinsics"
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `transform_config_path` | Path to the transform-specific config (see below). `fog_config_path` is also accepted for backward compatibility. |
+| `output_path` | Directory where outputs are written. |
+| `modalities` | Regular modalities that participate in sample-ID intersection. Which modalities are required depends on the transform (see table below). |
+| `hierarchical_modalities` | Per-scene data (e.g. intrinsics). Loaded once per scene and cached. |
+
+**Required modalities per transform:**
+
+| Transform | `modalities` | `hierarchical_modalities` |
+|---|---|---|
+| `fog` | `rgb`, `depth`, `semantic_segmentation` | — (intrinsics optional) |
+| `sky-depth` | `depth`, `semantic_segmentation` | — |
+| `radial` | `depth` | `intrinsics` |
+
+---
+
+## Fog Transform
+
+### Fog Config
+
+Controls the fog simulation.
+
+```json
+{
+  "airlight": "from_sky",
+  "seed": 1337,
+  "depth_scale": 1.0,
+  "resize_depth": true,
+  "contrast_threshold": 0.05,
+  "device": "cpu",
+  "gpu_batch_size": 4,
+  "selection": { ... },
+  "models": { ... }
+}
+```
+
+| Field | Description |
+|---|---|
+| `airlight` | **Required.** Airlight estimation method: `"from_sky"` (mean sky colour), `"dcp"` (dark channel prior), or `"dcp_heuristic"` (DCP with median heuristic). |
+| `seed` | Random seed for reproducibility. `null` for non-deterministic. |
+| `depth_scale` | Multiplier applied to depth values after loading. |
+| `resize_depth` | Resize the depth map to match the RGB resolution (bilinear). |
+| `contrast_threshold` | Threshold *C_t* used in the visibility-to-attenuation conversion (default `0.05`). |
+| `device` | `"cpu"`, `"cuda"`, `"mps"`, or `"gpu"` (alias for cuda). |
+| `gpu_batch_size` | Batch size when running on GPU. Uniform-model samples are batched; heterogeneous samples are processed individually. |
+
+### Fog Model
+
+The core equation is the **Koschmieder model** (atmospheric scattering):
+
+```
+I_fog(x) = I(x) * t(x)  +  L_s * (1 - t(x))
+```
+
+where:
+
+- **I(x)** is the original RGB colour at pixel *x*
+- **t(x) = exp(-k * d(x))** is the transmittance, which falls exponentially with depth *d* and attenuation coefficient *k*
+- **L_s** is the atmospheric light (airlight), i.e. the colour of the fog/sky light scattered towards the camera
+- **k** is derived from a meteorological visibility distance *V*: `k = -ln(C_t) / V`
+
+Distant objects are attenuated more (`t` approaches 0) and replaced by airlight, just as in real fog.
+
+### How Each Modality is Used
+
+**RGB** — The clean scene image. Normalised to float32 in [0, 1]. This is the *I(x)* term in the fog equation -- it gets blended with the airlight according to transmittance.
+
+**Depth** — A per-pixel depth map in **metres**. Provides the *d(x)* term in the transmittance calculation `t(x) = exp(-k * d(x))`. Pixels with greater depth receive more fog. Invalid values (NaN, inf, negative) are clamped to zero (treated as infinitely close, receiving no fog).
+
+**Semantic Segmentation** — A per-pixel semantic segmentation map from which a boolean sky mask is derived, loaded via euler-loading's dataset-specific `semantic_segmentation` loader. The sky mask is used for airlight estimation when the `airlight` method is `"from_sky"`: the mean RGB of all sky pixels in the clean image is used as the airlight colour *L_s*.
+
+**Intrinsics** *(optional)* — When present, planar (z-buffer) depth is converted to radial (Euclidean) depth before fog is applied.
+
+### Airlight Estimation
+
+The `airlight` config key selects how the atmospheric light *L_s* is estimated:
+
+| Method | Description |
+|---|---|
+| `from_sky` | Mean RGB of sky pixels in the clean image. Falls back to white `[1, 1, 1]` when no sky pixels exist. |
+| `dcp` | Dark Channel Prior — selects the brightest pixel (by channel sum) among the top 0.1% darkest-channel pixels. |
+| `dcp_heuristic` | DCP with median heuristic — selects the pixel closest to the median intensity (BT.601 grayscale) among the top 0.1% darkest-channel pixels. |
+
+GPU-native implementations (`DCPAirlightTorch`, `DCPHeuristicAirlightTorch`) are used automatically when running on GPU.
+
+### Model Selection
+
+Each image is assigned a fog model via the `selection` block:
+
+```json
+"selection": {
+  "mode": "weighted",
+  "weights": {
+    "uniform": 1.0,
+    "heterogeneous_k": 0.0,
+    "heterogeneous_ls": 0.0,
+    "heterogeneous_k_ls": 0.0
+  }
+}
+```
+
+- **`fixed`** mode: always use a single named model.
+- **`weighted`** mode: randomly select a model per image according to normalised weights.
+
+Four models are available:
+
+| Model | Description |
+|---|---|
+| `uniform` | Constant *k* and *L_s*. Standard homogeneous fog. |
+| `heterogeneous_k` | Spatially-varying *k*, constant *L_s*. Simulates patchy fog / fog banks. |
+| `heterogeneous_ls` | Constant *k*, spatially-varying *L_s*. Simulates scattered-light colour variation. |
+| `heterogeneous_k_ls` | Both *k* and *L_s* vary spatially. Most expressive model. |
+
+### Visibility Distribution
+
+Each model specifies a `visibility_m` distribution from which a visibility distance (in metres) is sampled per image:
+
+| `dist` | Parameters | Description |
+|---|---|---|
+| `constant` | `value` | Fixed value. |
+| `uniform` | `min`, `max` | Uniform random in range. |
+| `normal` | `mean`, `std`, optional `min`/`max` | Gaussian, optionally clamped. |
+| `lognormal` | `mean`, `sigma`, optional `min`/`max` | Log-normal. |
+| `choice` | `values`, optional `weights` | Discrete weighted choice. |
+
+The sampled visibility *V* is converted to the attenuation coefficient: **k = -ln(C_t) / V**.
+
+### Heterogeneous Noise Fields
+
+Both `k_hetero` and `ls_hetero` use Perlin FBM (fractional Brownian motion) to generate spatially-varying factor fields:
+
+```json
+"k_hetero": {
+  "scales": "auto",
+  "min_scale": 2,
+  "max_scale": null,
+  "min_factor": 0.0,
+  "max_factor": 1.0,
+  "normalize_to_mean": true
+}
+```
+
+The noise field (values in [0, 1]) is mapped to a factor field: `factor(x) = min_factor + (max_factor - min_factor) * noise(x)`. When `normalize_to_mean` is `true`, the factor field is rescaled so its spatial mean equals 1.0, preserving the overall fog density while introducing spatial variation.
+
+| Parameter | Effect |
+|---|---|
+| `min_factor` / `max_factor` | Range of the multiplicative factor. |
+| `normalize_to_mean` | Rescale factors so the image-wide mean equals the base value. Recommended for `k_hetero`. |
+| `scales` / `min_scale` / `max_scale` | Control spatial frequency content. |
+
+### Fog Output
+
+Foggy images are saved as PNG files organised by model name:
+
+```
+<output_path>/
+  uniform/
+    beta_0.0374_airlight_0.353_0.784_1_rgb_00000.png
+    config.json
+  heterogeneous_k/
+    ...
+```
+
+---
+
+## Sky-Depth Transform
+
+Overrides depth values in sky regions with a configurable constant. Useful for datasets where sky depth is encoded as zero or infinity and needs to be normalised to a large finite value.
+
+### Sky-Depth Config
+
+```json
+{
+  "sky_depth_value": 1000.0
+}
+```
+
+| Field | Description |
+|---|---|
+| `sky_depth_value` | Depth value assigned to all sky pixels. Defaults to `1000.0`. |
+
+### Sky-Depth Output
+
+Depth maps are saved as `.npy` float32 files preserving the original directory hierarchy.
+
+---
+
+## Radial Transform
+
+Converts planar (z-buffer) depth to radial (Euclidean) depth using camera intrinsics. For each pixel *(u, v)*:
+
+```
+d_radial(u, v) = d_planar(u, v) * sqrt(((u - cx)/fx)^2 + ((v - cy)/fy)^2 + 1)
+```
+
+### Radial Config
+
+```json
+{}
+```
+
+No special parameters are required. The transform reads intrinsics from the `intrinsics` hierarchical modality.
+
+### Radial Output
+
+Depth maps are saved as `.npy` float32 files preserving the original directory hierarchy.

euler_preprocess-1.0.1/README.md

@@ -0,0 +1,254 @@
+# euler-preprocess
+
+Physics-based preprocessing transforms for multi-modal RGB+depth datasets. Built on top of [euler-loading](https://github.com/d-rothen/euler-loading) and [ds-crawler](https://github.com/d-rothen/ds-crawler).
+
+Available transforms:
+
+| Command | Description |
+|---|---|
+| `euler-preprocess fog` | Synthetic fog via the Koschmieder atmospheric scattering model |
+| `euler-preprocess sky-depth` | Override depth values in sky regions with a constant |
+| `euler-preprocess radial` | Convert planar (z-buffer) depth to radial (Euclidean) depth |
+
+## Installation
+
+```bash
+uv pip install "euler-preprocess[gpu,progress] @ git+https://github.com/d-rothen/euler-fog"
+```
+
+## Usage
+
+```bash
+euler-preprocess fog       -c configs/example_dataset_config.json
+euler-preprocess sky-depth -c configs/sky_depth_dataset_config.json
+euler-preprocess radial    -c configs/radial_dataset_config.json
+```
+
+## Configuration
+
+Every subcommand takes a **dataset config** JSON that points to the input data and a **transform config**. Each modality path must be a directory indexed by [ds-crawler](https://github.com/d-rothen/ds-crawler) with an `euler_loading` property that specifies the loader and function. This allows euler-loading to auto-select the correct dataset-specific loader.
+
+### Dataset Config
+
+```json
+{
+  "transform_config_path": "configs/run1.json",
+  "output_path": "/path/to/output",
+  "modalities": {
+    "rgb": "/path/to/rgb",
+    "depth": "/path/to/depth",
+    "semantic_segmentation": "/path/to/classSegmentation"
+  },
+  "hierarchical_modalities": {
+    "intrinsics": "/path/to/intrinsics"
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `transform_config_path` | Path to the transform-specific config (see below). `fog_config_path` is also accepted for backward compatibility. |
+| `output_path` | Directory where outputs are written. |
+| `modalities` | Regular modalities that participate in sample-ID intersection. Which modalities are required depends on the transform (see table below). |
+| `hierarchical_modalities` | Per-scene data (e.g. intrinsics). Loaded once per scene and cached. |
+
+**Required modalities per transform:**
+
+| Transform | `modalities` | `hierarchical_modalities` |
+|---|---|---|
+| `fog` | `rgb`, `depth`, `semantic_segmentation` | — (intrinsics optional) |
+| `sky-depth` | `depth`, `semantic_segmentation` | — |
+| `radial` | `depth` | `intrinsics` |
+
+---
+
+## Fog Transform
+
+### Fog Config
+
+Controls the fog simulation.
+
+```json
+{
+  "airlight": "from_sky",
+  "seed": 1337,
+  "depth_scale": 1.0,
+  "resize_depth": true,
+  "contrast_threshold": 0.05,
+  "device": "cpu",
+  "gpu_batch_size": 4,
+  "selection": { ... },
+  "models": { ... }
+}
+```
+
+| Field | Description |
+|---|---|
+| `airlight` | **Required.** Airlight estimation method: `"from_sky"` (mean sky colour), `"dcp"` (dark channel prior), or `"dcp_heuristic"` (DCP with median heuristic). |
+| `seed` | Random seed for reproducibility. `null` for non-deterministic. |
+| `depth_scale` | Multiplier applied to depth values after loading. |
+| `resize_depth` | Resize the depth map to match the RGB resolution (bilinear). |
+| `contrast_threshold` | Threshold *C_t* used in the visibility-to-attenuation conversion (default `0.05`). |
+| `device` | `"cpu"`, `"cuda"`, `"mps"`, or `"gpu"` (alias for cuda). |
+| `gpu_batch_size` | Batch size when running on GPU. Uniform-model samples are batched; heterogeneous samples are processed individually. |
+
+### Fog Model
+
+The core equation is the **Koschmieder model** (atmospheric scattering):
+
+```
+I_fog(x) = I(x) * t(x)  +  L_s * (1 - t(x))
+```
+
+where:
+
+- **I(x)** is the original RGB colour at pixel *x*
+- **t(x) = exp(-k * d(x))** is the transmittance, which falls exponentially with depth *d* and attenuation coefficient *k*
+- **L_s** is the atmospheric light (airlight), i.e. the colour of the fog/sky light scattered towards the camera
+- **k** is derived from a meteorological visibility distance *V*: `k = -ln(C_t) / V`
+
+Distant objects are attenuated more (`t` approaches 0) and replaced by airlight, just as in real fog.
+
+### How Each Modality is Used
+
+**RGB** — The clean scene image. Normalised to float32 in [0, 1]. This is the *I(x)* term in the fog equation -- it gets blended with the airlight according to transmittance.
+
+**Depth** — A per-pixel depth map in **metres**. Provides the *d(x)* term in the transmittance calculation `t(x) = exp(-k * d(x))`. Pixels with greater depth receive more fog. Invalid values (NaN, inf, negative) are clamped to zero (treated as infinitely close, receiving no fog).
+
+**Semantic Segmentation** — A per-pixel semantic segmentation map from which a boolean sky mask is derived, loaded via euler-loading's dataset-specific `semantic_segmentation` loader. The sky mask is used for airlight estimation when the `airlight` method is `"from_sky"`: the mean RGB of all sky pixels in the clean image is used as the airlight colour *L_s*.
+
+**Intrinsics** *(optional)* — When present, planar (z-buffer) depth is converted to radial (Euclidean) depth before fog is applied.
+
+### Airlight Estimation
+
+The `airlight` config key selects how the atmospheric light *L_s* is estimated:
+
+| Method | Description |
+|---|---|
+| `from_sky` | Mean RGB of sky pixels in the clean image. Falls back to white `[1, 1, 1]` when no sky pixels exist. |
+| `dcp` | Dark Channel Prior — selects the brightest pixel (by channel sum) among the top 0.1% darkest-channel pixels. |
+| `dcp_heuristic` | DCP with median heuristic — selects the pixel closest to the median intensity (BT.601 grayscale) among the top 0.1% darkest-channel pixels. |
+
+GPU-native implementations (`DCPAirlightTorch`, `DCPHeuristicAirlightTorch`) are used automatically when running on GPU.
+
+### Model Selection
+
+Each image is assigned a fog model via the `selection` block:
+
+```json
+"selection": {
+  "mode": "weighted",
+  "weights": {
+    "uniform": 1.0,
+    "heterogeneous_k": 0.0,
+    "heterogeneous_ls": 0.0,
+    "heterogeneous_k_ls": 0.0
+  }
+}
+```
+
+- **`fixed`** mode: always use a single named model.
+- **`weighted`** mode: randomly select a model per image according to normalised weights.
+
+Four models are available:
+
+| Model | Description |
+|---|---|
+| `uniform` | Constant *k* and *L_s*. Standard homogeneous fog. |
+| `heterogeneous_k` | Spatially-varying *k*, constant *L_s*. Simulates patchy fog / fog banks. |
+| `heterogeneous_ls` | Constant *k*, spatially-varying *L_s*. Simulates scattered-light colour variation. |
+| `heterogeneous_k_ls` | Both *k* and *L_s* vary spatially. Most expressive model. |
+
+### Visibility Distribution
+
+Each model specifies a `visibility_m` distribution from which a visibility distance (in metres) is sampled per image:
+
+| `dist` | Parameters | Description |
+|---|---|---|
+| `constant` | `value` | Fixed value. |
+| `uniform` | `min`, `max` | Uniform random in range. |
+| `normal` | `mean`, `std`, optional `min`/`max` | Gaussian, optionally clamped. |
+| `lognormal` | `mean`, `sigma`, optional `min`/`max` | Log-normal. |
+| `choice` | `values`, optional `weights` | Discrete weighted choice. |
+
+The sampled visibility *V* is converted to the attenuation coefficient: **k = -ln(C_t) / V**.
+
+### Heterogeneous Noise Fields
+
+Both `k_hetero` and `ls_hetero` use Perlin FBM (fractional Brownian motion) to generate spatially-varying factor fields:
+
+```json
+"k_hetero": {
+  "scales": "auto",
+  "min_scale": 2,
+  "max_scale": null,
+  "min_factor": 0.0,
+  "max_factor": 1.0,
+  "normalize_to_mean": true
+}
+```
+
+The noise field (values in [0, 1]) is mapped to a factor field: `factor(x) = min_factor + (max_factor - min_factor) * noise(x)`. When `normalize_to_mean` is `true`, the factor field is rescaled so its spatial mean equals 1.0, preserving the overall fog density while introducing spatial variation.
+
+| Parameter | Effect |
+|---|---|
+| `min_factor` / `max_factor` | Range of the multiplicative factor. |
+| `normalize_to_mean` | Rescale factors so the image-wide mean equals the base value. Recommended for `k_hetero`. |
+| `scales` / `min_scale` / `max_scale` | Control spatial frequency content. |
+
+### Fog Output
+
+Foggy images are saved as PNG files organised by model name:
+
+```
+<output_path>/
+  uniform/
+    beta_0.0374_airlight_0.353_0.784_1_rgb_00000.png
+    config.json
+  heterogeneous_k/
+    ...
+```
+
+---
+
+## Sky-Depth Transform
+
+Overrides depth values in sky regions with a configurable constant. Useful for datasets where sky depth is encoded as zero or infinity and needs to be normalised to a large finite value.
+
+### Sky-Depth Config
+
+```json
+{
+  "sky_depth_value": 1000.0
+}
+```
+
+| Field | Description |
+|---|---|
+| `sky_depth_value` | Depth value assigned to all sky pixels. Defaults to `1000.0`. |
+
+### Sky-Depth Output
+
+Depth maps are saved as `.npy` float32 files preserving the original directory hierarchy.
+
+---
+
+## Radial Transform
+
+Converts planar (z-buffer) depth to radial (Euclidean) depth using camera intrinsics. For each pixel *(u, v)*:
+
+```
+d_radial(u, v) = d_planar(u, v) * sqrt(((u - cx)/fx)^2 + ((v - cy)/fy)^2 + 1)
+```
+
+### Radial Config
+
+```json
+{}
+```
+
+No special parameters are required. The transform reads intrinsics from the `intrinsics` hierarchical modality.
+
+### Radial Output
+
+Depth maps are saved as `.npy` float32 files preserving the original directory hierarchy.

euler_preprocess-1.0.1/euler_preprocess/cli.py

@@ -0,0 +1,150 @@
+"""CLI entry point for euler-preprocess.
+
+Used both by ``python main.py`` and by the installed ``euler-preprocess`` console
+script.  Supports subcommands: ``fog``, ``sky-depth``, ``radial``.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from euler_preprocess.common.dataset import build_dataset
+from euler_preprocess.common.logging import get_logger, log_dataset_info
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve(path_str: str, config_dir: Path) -> Path:
+    """Resolve a path relative to the config file's directory."""
+    p = Path(path_str)
+    if p.is_absolute():
+        return p
+    return (config_dir / p).resolve()
+
+
+def _run_transform(args: argparse.Namespace, transform_class: type) -> int:
+    """Shared logic for all subcommands."""
+    logger = get_logger()
+
+    config_path = Path(args.config).resolve()
+    config_dir = config_path.parent
+
+    with open(config_path, "r", encoding="utf-8") as f:
+        config = json.load(f)
+
+    # Resolve the transform-specific config path.
+    # Support both ``transform_config_path`` and legacy ``fog_config_path``.
+    transform_config_key = "transform_config_path"
+    if transform_config_key not in config:
+        transform_config_key = "fog_config_path"
+    transform_config_path = _resolve(config[transform_config_key], config_dir)
+    output_path = config["output_path"]
+
+    # Read the transform config to determine the device (for dataset logging)
+    with open(transform_config_path, "r", encoding="utf-8") as f:
+        transform_cfg = json.load(f)
+    device = transform_cfg.get("device", "cpu").lower()
+    use_gpu = device not in ("cpu",)
+
+    logger.info("Config: %s", args.config)
+    logger.info("Transform config: %s", transform_config_path)
+    logger.info("Output path: %s", output_path)
+
+    required_modalities = transform_class.REQUIRED_MODALITIES
+    required_hierarchical = transform_class.REQUIRED_HIERARCHICAL_MODALITIES or None
+    dataset = build_dataset(config, required_modalities, required_hierarchical)
+    dataset_name = config.get("dataset", "dataset")
+
+    modality_paths = {
+        **config.get("modalities", {}),
+        **config.get("hierarchical_modalities", {}),
+    }
+    log_dataset_info(logger, dataset_name, len(dataset), modality_paths, use_gpu)
+
+    transform = transform_class(
+        config_path=str(transform_config_path),
+        out_path=output_path,
+    )
+
+    saved_paths = transform.run(dataset)
+
+    logger.info("Transform complete. Generated %d outputs.", len(saved_paths))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Subcommand handlers
+# ---------------------------------------------------------------------------
+
+def _cmd_fog(args: argparse.Namespace) -> int:
+    from euler_preprocess.fog.transform import FogTransform
+    return _run_transform(args, FogTransform)
+
+
+def _cmd_sky_depth(args: argparse.Namespace) -> int:
+    from euler_preprocess.sky_depth.transform import SkyDepthTransform
+    return _run_transform(args, SkyDepthTransform)
+
+
+def _cmd_radial(args: argparse.Namespace) -> int:
+    from euler_preprocess.radial.transform import RadialTransform
+    return _run_transform(args, RadialTransform)
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Preprocessing transforms for RGB+depth datasets.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # --- fog ---
+    fog_parser = subparsers.add_parser(
+        "fog", help="Apply synthetic fog to RGB images.",
+    )
+    fog_parser.add_argument(
+        "--config", "-c", type=str, required=True,
+        help="Path to the dataset configuration JSON file.",
+    )
+    fog_parser.set_defaults(func=_cmd_fog)
+
+    # --- sky-depth ---
+    sky_depth_parser = subparsers.add_parser(
+        "sky-depth", help="Override sky-region depth values.",
+    )
+    sky_depth_parser.add_argument(
+        "--config", "-c", type=str, required=True,
+        help="Path to the dataset configuration JSON file.",
+    )
+    sky_depth_parser.set_defaults(func=_cmd_sky_depth)
+
+    # --- radial ---
+    radial_parser = subparsers.add_parser(
+        "radial", help="Convert planar (z-buffer) depth to radial (Euclidean) depth.",
+    )
+    radial_parser.add_argument(
+        "--config", "-c", type=str, required=True,
+        help="Path to the dataset configuration JSON file.",
+    )
+    radial_parser.set_defaults(func=_cmd_radial)
+
+    args = parser.parse_args()
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return parser.parse_args(["--help"])
+    return args
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    args = parse_args()
+    return args.func(args)