euler-inference 2.0.1__tar.gz

euler_inference-2.0.1/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: euler-inference
+Version: 2.0.1
+Summary: Modality-agnostic inference pipeline using euler-loading
+Author-email: Daniel Rothenpieler <rothenpielerdaniel@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy
+Requires-Dist: Pillow
+Requires-Dist: euler-loading
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"

euler_inference-2.0.1/README.md

@@ -0,0 +1,471 @@
+# euler-inference
+
+A modality-agnostic inference pipeline for running models against [euler-loading](https://github.com/d-rothen/euler-loading) datasets. Your model receives all loaded modalities as a dict and returns predictions — the pipeline handles data loading, source-aware output writing, and dataset indexing.
+
+## Install
+
+```sh
+pip install -e .
+uv pip install "euler-inference @ git+https://github.com/d-rothen/euler-inference"
+```
+
+## How it works
+
+1. You point the pipeline at a **model** (a `.py` file with a `Model` class) and a **dataset** (modality paths indexed by [ds-crawler](https://github.com/d-rothen/ds-crawler))
+2. [euler-loading](https://github.com/d-rothen/euler-loading) loads each sample, auto-resolving loaders from each dataset's `output.json` metadata
+3. All loaded modalities are passed to your model's `predict()` as a flat dict
+4. Predictions either mirror an input modality via `euler-loading` writers, or fall back to the legacy serializer when no source modality is available
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Model Contract](#model-contract)
+- [Model Cards](#model-cards)
+- [Configuration](#configuration)
+  - [JSON Config](#json-config)
+  - [CLI Flags](#cli-flags)
+  - [Python API](#python-api)
+- [Output Behaviour](#output-behaviour)
+- [SLURM / HPC Usage](#slurm--hpc-usage)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+### With a model card (recommended)
+
+```bash
+euler-inference \
+    --model-card model_card.json \
+    --set weights=/path/to/checkpoint.pt \
+    --data rgb=/data/vkitti2/rgb \
+    -o /output/predictions
+```
+
+### With a JSON config
+
+```bash
+euler-inference -c config.json
+```
+
+### From Python
+
+```python
+from euler_inference.api import infer
+
+infer(
+    model_path="/path/to/model.py",
+    output_base_path="/output/predictions",
+    dataset_modalities={"rgb": "/data/vkitti2/rgb"},
+)
+```
+
+## Model Contract
+
+Your model file must define a class named `Model` with the following interface. The file is loaded in-process via `importlib` — no subprocesses, no serialization.
+
+### Required
+
+```python
+class Model:
+    def __init__(self, config: dict, device: str | None = None):
+        """Called once when the pipeline starts."""
+        ...
+
+    def predict(self, inputs: dict) -> dict:
+        """Called once per sample. Receives all loaded modalities, returns predictions."""
+        ...
+```
+
+**`__init__`** receives:
+- `config` — the `model_config` dict from your config (empty `{}` if omitted)
+- `device` — device string (`"cuda"`, `"cpu"`, `"mps"`) or `None` for auto-detect
+
+**`predict`** receives a dict of **all loaded modalities by name**. The keys match the modality names from the dataset config. For example, with `{"rgb": "/data/rgb", "depth": "/data/depth"}` and hierarchical `{"textgt": "/data/textgt"}`:
+
+```python
+inputs = {
+    "rgb": <loaded rgb data>,        # numpy array, tensor, etc.
+    "depth": <loaded depth data>,
+    "textgt": {"intrinsics": ...},   # hierarchical: dict of file_id -> data
+}
+```
+
+The exact types depend on the loaders configured in each dataset's `output.json` (resolved automatically by euler-loading). If euler-loading has access to torch/CUDA, it will use GPU loaders where available.
+
+**`predict`** must return a dict whose keys match the `key` fields in your `outputs` config. Each value should be a `np.ndarray`.
+
+### Optional metadata
+
+Models can declare class-level attributes so pipelines don't need to know model internals:
+
+```python
+class Model:
+    OUTPUTS = [
+        {"key": "depth", "type": "npy"},
+        {"key": "confidence", "type": "png"},
+    ]
+
+    DEFAULT_CONFIG = {
+        "backbone": "resnet50",
+        "num_scales": 4,
+    }
+
+    def __init__(self, config, device=None): ...
+    def predict(self, inputs): ...
+```
+
+**`OUTPUTS`** — When the config omits `outputs`, the pipeline reads `OUTPUTS` from the Model class. If both omit it, the pipeline default (`[{"key": "depth", "type": "npy"}]`) is used.
+
+**`DEFAULT_CONFIG`** — Merged under user-provided `model_config` (user values win). For example, `DEFAULT_CONFIG = {"backbone": "resnet50", "num_scales": 4}` with user config `{"backbone": "efficientnet"}` produces `{"backbone": "efficientnet", "num_scales": 4}`.
+
+### Rules and gotchas
+
+- The class **must** be named `Model` (case-sensitive)
+- Relative imports don't work (loaded via importlib). Add your model's directory to `sys.path`:
+  ```python
+  import sys
+  from pathlib import Path
+  sys.path.insert(0, str(Path(__file__).parent))
+  ```
+- Your model runs **in the same process** — all dependencies must be importable in the active environment
+- `predict` is called **once per sample** (no batching by the pipeline)
+- Lazy-loading weights inside `predict` on first call is a recommended pattern
+
+A full template is at [`examples/model_template.py`](examples/model_template.py).
+
+## Model Cards
+
+Model cards separate the model's self-description from runtime configuration. The model author ships a `model_card.json` alongside `model.py`; the pipeline operator provides runtime values via placeholder bindings.
+
+### Placeholder syntax
+
+```
+{{type:name}}
+```
+
+- `type` is informational (used by external UIs for typed pickers): `checkpoint`, `modality`, `hierarchical_modality`, `simple_path`, etc.
+- `name` is the binding key used for resolution
+
+### Example card
+
+```json
+{
+    "model": "./model.py",
+    "checkpoint": "{{checkpoint:weights}}",
+    "config": {
+        "backbone": "resnet50"
+    },
+    "inputs": {
+        "rgb": "{{modality:rgb}}"
+    },
+    "hierarchical_inputs": {
+        "textgt": "{{hierarchical_modality:textgt}}"
+    },
+    "outputs": [
+        {"key": "depth", "type": "npy"}
+    ]
+}
+```
+
+### CLI usage
+
+```bash
+euler-inference \
+    --model-card model_card.json \
+    --set weights=/path/to/checkpoint.pt \
+    --data rgb=/data/vkitti2/rgb \
+    --hierarchical-data textgt=/data/vkitti2/textgt \
+    -o /output/predictions
+```
+
+### Python usage
+
+```python
+from euler_inference.api import infer
+
+# From a card file
+infer(
+    model_card="model_card.json",
+    bindings={"weights": "/path/to/checkpoint.pt"},
+    data={"rgb": "/data/rgb"},
+    output_base_path="/output",
+)
+
+# From an already-resolved dict (e.g. from a server)
+infer(
+    model_card={"model": "/abs/path/model.py", "inputs": {"rgb": "/data/rgb"}, ...},
+    output_base_path="/output",
+)
+```
+
+### Card fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `model` | Yes | Relative path to model.py (resolved from card directory) |
+| `checkpoint` | No | Checkpoint path (injected into model_config as `config["checkpoint"]`) |
+| `config` | No | Model-specific config dict (merged with checkpoint) |
+| `inputs` | Yes | Modality name -> path mapping |
+| `hierarchical_inputs` | No | Hierarchical modality name -> path mapping |
+| `outputs` | No | Output configuration (falls back to model `OUTPUTS` or pipeline default) |
+
+## Configuration
+
+### JSON Config
+
+For simpler setups without placeholders, use a monolithic JSON config:
+
+```json
+{
+    "external_model": {
+        "model_path": "/absolute/path/to/model.py",
+        "model_config": {
+            "checkpoint": "/path/to/weights.pt"
+        }
+    },
+    "dataset": {
+        "modalities": {
+            "rgb": "/data/vkitti2/rgb"
+        },
+        "hierarchical_modalities": {
+            "textgt": "/data/vkitti2/textgt"
+        }
+    },
+    "outputs": [
+        {"key": "depth", "type": "npy"},
+        {"key": "confidence", "type": "png", "suffix": ""}
+    ],
+    "output_base_path": "/output/predictions",
+    "device": "cuda",
+    "max_samples": null,
+    "zip": false,
+    "strict": true
+}
+```
+
+#### Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `external_model.model_path` | string | Yes | **Absolute** path to model `.py` file |
+| `external_model.model_config` | object/string | No | Model-specific config (dict or path to JSON). Passed as `config` to `Model.__init__`. Defaults to `{}`. |
+| `dataset.modalities` | object | Yes | Map of modality names to their root paths |
+| `dataset.hierarchical_modalities` | object | No | Map of hierarchical modality names to paths |
+| `outputs` | list | No | What to save from the model's output dict. Defaults to `[{"key": "depth", "type": "npy"}]`. |
+| `outputs[].key` | string | Yes | Key in the dict returned by `Model.predict()` |
+| `outputs[].type` | string | Yes | Legacy file format: `npy`, `png`, `jpg`, `jpeg`, `exr`. Used when no source-backed writer is available. |
+| `outputs[].suffix` | string | No | Legacy filename suffix before extension. Defaults to `_<key>`. Ignored for source-backed outputs. |
+| `outputs[].source_modality` | string | No | Regular input modality whose `euler-loading` writer/path should be mirrored under `output_base_path/<key>/`. Defaults to `key` when it matches a regular input modality. |
+| `outputs[].writer` | object | No | Override ds-crawler writer metadata for legacy outputs (see [Writer metadata](#writer-metadata)) |
+| `output_base_path` | string | Yes* | Base directory for predictions. Can be omitted if supplied via `-o`. |
+| `device` | string | No | `"cuda"`, `"cpu"`, `"mps"`. Auto-detected if omitted. |
+| `max_samples` | int | No | Limit samples to process. `null` for all. |
+| `zip` | bool | No | Write outputs as `.zip` archives instead of directories. Source-backed outputs preserve source filenames and extensions inside the archive. Default `false`. |
+| `strict` | bool | No | Enforce writer metadata for known modality types. Default `true`. |
+
+### CLI Flags
+
+Runtime overrides so configs don't need to embed pipeline-specific values:
+
+```bash
+euler-inference -c config.json \
+    -o /scratch/predictions \
+    -d cuda \
+    -n 1000 \
+    --zip \
+    --no-strict
+```
+
+| Flag | Description |
+|------|-------------|
+| `-c`, `--config` | Path to JSON config file |
+| `--model-card` | Path to model card JSON (mutually exclusive with `-c`) |
+| `--set KEY=VALUE` | Set a placeholder binding |
+| `--data KEY=VALUE` | Set an input modality path binding |
+| `--hierarchical-data KEY=VALUE` | Set a hierarchical input path binding |
+| `-o`, `--output-base-path` | Override output directory |
+| `-d`, `--device` | Override device |
+| `-n`, `--max-samples` | Override max samples |
+| `--zip` | Write outputs as zip archives |
+| `--no-strict` | Disable strict writer metadata validation |
+| `-v`, `--verbose` | Enable verbose logging |
+
+### Python API
+
+```python
+from euler_inference.api import infer
+
+infer(
+    model_path="/path/to/model.py",
+    output_base_path="/output",
+    dataset_modalities={"rgb": "/data/rgb"},
+    dataset_hierarchical_modalities={"textgt": "/data/textgt"},
+    model_config={"checkpoint": "/path/to/weights.pt"},
+    outputs=[{"key": "depth", "type": "npy"}],
+    device="cuda",
+    max_samples=100,
+    zip=False,
+    strict=True,
+    verbose=True,
+)
+```
+
+When `outputs` is omitted, the pipeline resolves outputs from the model's `OUTPUTS` attribute, then falls back to the pipeline default.
+
+## Output Behaviour
+
+### Source-backed outputs
+
+When `outputs[].source_modality` is set, or the output key matches a regular input modality, the pipeline uses `MultiModalDataset.write_sample()` and the source modality's `euler-loading` writer. Files are written under `output_base_path/<output_key>/` using the source modality's relative path, basename, and extension:
+
+```
+output_base_path/
+└── rgb/
+    ├── .ds-crawler/output.json         # ds-crawler index
+    └── Scene01/clone/Camera_0/
+        ├── 00001.png
+        ├── 00002.png
+        └── ...
+```
+
+This keeps the output format aligned with the read-in format. The output dataset metadata is initialized from the source modality index, so the mirrored output stays loadable by `euler-loading`.
+
+With `--zip`, the same source-backed output is written into one archive per output key:
+
+```
+output_base_path/
+└── rgb.zip
+    ├── .ds-crawler/output.json
+    └── Scene01/clone/Camera_0/
+        ├── 00001.png
+        ├── 00002.png
+        └── ...
+```
+
+### Legacy outputs
+
+If no source modality can be resolved for an output, the pipeline falls back to the legacy serializer and writes files as `{sample_id}{suffix}.{type}`:
+
+```
+output_base_path/
+└── depth/
+    ├── .ds-crawler/output.json
+    └── Scene01/clone/Camera_0/
+        ├── 00001_depth.npy
+        └── ...
+```
+
+### Writer metadata
+
+Source-backed outputs use ds-crawler writer backends configured from the source modality's `output.json`, so their dataset metadata mirrors the read-in modality.
+
+Legacy outputs are written via ds-crawler's `DatasetWriter`/`ZipDatasetWriter`, which generates an `output.json` index for the output dataset. The writer receives these fields:
+
+| Field | Default | Override via |
+|-------|---------|-------------|
+| `name` | Input dataset's name (from its `output.json`), or the output key if unavailable | `outputs[].writer.name` |
+| `type` | Output key (e.g. `"depth"`) | `outputs[].writer.type` |
+| `euler_train` | `{"used_as": "target", "modality_type": "<key>"}` | `outputs[].writer.euler_train` |
+| `euler_loading` | *(omitted)* | `outputs[].writer.euler_loading` |
+| `separator` | `null` | — |
+| `meta` | *(omitted)* | `outputs[].writer.meta` |
+
+In `--no-strict` mode, `modality_type` defaults to `"other"` instead of the output key, which bypasses ds-crawler's metadata validation for known types (depth, rgb, etc.).
+
+#### `euler_loading`
+
+When the output dataset should be loadable by [euler-loading](https://github.com/d-rothen/euler-loading) without an explicit loader, set `euler_loading` with the `loader` (module name) and `function` (callable name) that euler-loading should use to auto-resolve a loader from the output's `output.json`. Available loaders: `vkitti2`, `real_drive_sim`, `generic_dense_depth`.
+
+You can also include `used_as`, `modality_type`, `slot`, and `task` — these are consulted by euler-loading's `describe_for_runlog()` for experiment metadata.
+
+Example with explicit writer overrides:
+
+```json
+{
+    "outputs": [
+        {
+            "key": "depth",
+            "type": "npy",
+            "writer": {
+                "name": "my_dataset",
+                "euler_train": {"used_as": "target", "modality_type": "depth"},
+                "euler_loading": {"loader": "generic_dense_depth", "function": "depth"},
+                "meta": {"radial_depth": false, "scale_to_meters": 1.0, "range": [0, 100]}
+            }
+        }
+    ]
+}
+```
+
+### Supported output formats
+
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| NumPy | `npy` | Preserves full float precision |
+| PNG | `png` | Float arrays clipped to [0,1] and scaled to uint8. Supports grayscale, RGB, RGBA. |
+| JPEG | `jpg`/`jpeg` | Same as PNG but lossy. |
+| OpenEXR | `exr` | Full float precision. Requires `pip install OpenEXR`. Not supported in zip mode. |
+
+### Image output conversion
+
+When saving to `png`/`jpg`:
+- `float32`/`float64` arrays are clipped to [0, 1] and scaled to uint8
+- Other dtypes are cast to `uint8`
+- 2D arrays are saved as grayscale, (H, W, 3) as RGB, (H, W, 4) as RGBA
+
+## SLURM / HPC Usage
+
+```bash
+#!/bin/bash
+#SBATCH --job-name=inference
+#SBATCH --gres=gpu:1
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=32G
+
+source /path/to/venv/bin/activate
+
+euler-inference \
+    --model-card /path/to/model_card.json \
+    --set weights=/path/to/checkpoint.pt \
+    --data rgb=/data/vkitti2/rgb \
+    -o /scratch/$SLURM_JOB_ID/output
+```
+
+Key points:
+- Your model runs in-process, so the active environment must have all dependencies (both euler-inference's and your model's)
+- GPU allocation from SLURM (`CUDA_VISIBLE_DEVICES`) is available directly
+- euler-loading will automatically use GPU loaders when torch/CUDA is available
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## Troubleshooting
+
+### "model_path must be absolute"
+Use absolute paths in your config:
+```json
+"model_path": "/hpc/users/me/models/model.py"
+```
+
+### ImportError when loading your model
+Your model runs in the same process. All of your model's dependencies must be installed in the active Python environment.
+
+### Relative imports don't work in model.py
+Add your model's directory to `sys.path`:
+```python
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent))
+```
+
+### "Model did not return '<key>' key"
+Your `predict()` return dict is missing a key that the `outputs` config expects. Make sure the keys match.
+
+### "meta is required for modality_type='depth'"
+In strict mode (default), ds-crawler requires metadata for known modality types. Either:
+- Add a `writer.meta` dict to your output config with the required fields
+- Use `--no-strict` to bypass validation

euler_inference-2.0.1/euler_inference/__init__.py

@@ -0,0 +1,8 @@
+"""Model inference pipeline using euler-loading."""
+
+# Note: We don't import submodules here to avoid RuntimeWarning when running
+# `python -m euler_inference`. Import directly from submodules instead:
+#   from euler_inference.config import InferenceConfig
+#   from euler_inference.inference import run_inference
+
+__all__ = ["config", "inference", "models"]

euler_inference-2.0.1/euler_inference/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m euler_inference``."""
+
+from euler_inference.inference import main
+
+main()