euler-inference 2.7.0__tar.gz → 2.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- euler_inference-2.9.0/PKG-INFO +361 -0
- euler_inference-2.9.0/README.md +342 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/_outputs.py +215 -4
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/api.py +11 -4
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/config.py +118 -15
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/inference.py +95 -27
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/model_card.py +24 -8
- euler_inference-2.9.0/euler_inference.egg-info/PKG-INFO +361 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/SOURCES.txt +2 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/pyproject.toml +16 -1
- {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_intrinsics_resolution.py +19 -11
- {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_model_card.py +3 -5
- {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_model_metadata.py +5 -5
- euler_inference-2.9.0/tests/test_sampling.py +141 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_save_path.py +0 -88
- euler_inference-2.9.0/tests/test_source_grid.py +178 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_writer_integration.py +49 -4
- euler_inference-2.7.0/PKG-INFO +0 -13
- euler_inference-2.7.0/README.md +0 -613
- euler_inference-2.7.0/euler_inference.egg-info/PKG-INFO +0 -13
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/__init__.py +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/__main__.py +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/models/__init__.py +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/models/external_model.py +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/dependency_links.txt +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/entry_points.txt +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/requires.txt +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/top_level.txt +0 -0
- {euler_inference-2.7.0 → euler_inference-2.9.0}/setup.cfg +0 -0
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: euler-inference
|
|
3
|
+
Version: 2.9.0
|
|
4
|
+
Summary: Modality-agnostic inference pipeline using euler-loading
|
|
5
|
+
Author-email: Daniel Rothenpieler <rothenpielerdaniel@gmail.com>
|
|
6
|
+
Project-URL: Homepage, https://github.com/d-rothen/euler-inference
|
|
7
|
+
Project-URL: Repository, https://github.com/d-rothen/euler-inference
|
|
8
|
+
Project-URL: Issues, https://github.com/d-rothen/euler-inference/issues
|
|
9
|
+
Keywords: machine-learning,inference,multimodal,datasets
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
Requires-Dist: torch>=2.0.0
|
|
13
|
+
Requires-Dist: numpy
|
|
14
|
+
Requires-Dist: Pillow
|
|
15
|
+
Requires-Dist: euler-loading
|
|
16
|
+
Requires-Dist: tqdm
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: pytest; extra == "dev"
|
|
19
|
+
|
|
20
|
+
<!-- euler header — shared across the euler packages.
|
|
21
|
+
Per package, change only: the <h1>, the tagline, and the badge URLs. -->
|
|
22
|
+
<p align="center">
|
|
23
|
+
<img src="https://files.chronodle.com/icons/euler.svg" alt="euler" width="96" height="96">
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<h1 align="center">euler-inference</h1>
|
|
27
|
+
|
|
28
|
+
<p align="center">
|
|
29
|
+
<em>A small, modality-agnostic runner for applying Python models to indexed datasets.</em>
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<a href="https://pypi.org/project/euler-inference/"><img alt="PyPI" src="https://img.shields.io/pypi/v/euler-inference?color=0A7BBB"></a>
|
|
34
|
+
<a href="https://www.python.org/"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
`euler-inference` connects an in-process model to one or more
|
|
40
|
+
[`euler-loading`](https://github.com/d-rothen/euler-loading) modalities. It
|
|
41
|
+
intersects their dataset IDs, loads synchronized samples, runs `predict()`, and
|
|
42
|
+
writes indexed outputs while preserving source paths when possible.
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
indexed modalities → euler-loading → Model.predict(inputs) → indexed outputs
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Quick start
|
|
49
|
+
|
|
50
|
+
Install the package:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install euler-inference
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Create a model file. The pipeline deliberately keeps the contract tiny:
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
# /absolute/path/to/model.py
|
|
60
|
+
import numpy as np
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class Model:
|
|
64
|
+
OUTPUTS = [{"key": "depth", "type": "npy"}]
|
|
65
|
+
|
|
66
|
+
def __init__(self, config: dict, device: str | None = None):
|
|
67
|
+
self.scale = config.get("scale", 1.0)
|
|
68
|
+
|
|
69
|
+
def predict(self, inputs: dict) -> dict:
|
|
70
|
+
height, width = inputs["rgb"].shape[-2:]
|
|
71
|
+
depth = np.ones((height, width), dtype=np.float32) * self.scale
|
|
72
|
+
return {"depth": depth}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Point a config at the model and an indexed modality:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"external_model": {
|
|
80
|
+
"model_path": "/absolute/path/to/model.py",
|
|
81
|
+
"model_config": {"scale": 2.0}
|
|
82
|
+
},
|
|
83
|
+
"dataset": {
|
|
84
|
+
"modalities": {"rgb": "/data/vkitti2/rgb"}
|
|
85
|
+
},
|
|
86
|
+
"output_base_path": "/data/predictions",
|
|
87
|
+
"sample": 0.1,
|
|
88
|
+
"sample_mode": "random"
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Run it:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
euler-inference --config config.json
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The dataset directories or zip archives must contain `ds-crawler` metadata.
|
|
99
|
+
`euler-loading` resolves each loader from that metadata, so the model receives
|
|
100
|
+
the native loaded value: for example a NumPy array or torch tensor.
|
|
101
|
+
|
|
102
|
+
## Sampling
|
|
103
|
+
|
|
104
|
+
`sample` limits work before any files are loaded:
|
|
105
|
+
|
|
106
|
+
| Value | Meaning |
|
|
107
|
+
| --- | --- |
|
|
108
|
+
| omitted | Process every synchronized dataset ID |
|
|
109
|
+
| integer greater than `1` | Process at most that many IDs |
|
|
110
|
+
| float between `0` and `1` | Process that fraction of all IDs |
|
|
111
|
+
|
|
112
|
+
Fractional counts round down, with a minimum of one sample for a non-empty
|
|
113
|
+
dataset. Counts larger than the dataset are capped at its size.
|
|
114
|
+
|
|
115
|
+
`sample_mode` controls which IDs are chosen:
|
|
116
|
+
|
|
117
|
+
- `sequential` (default) selects the first IDs in dataset order.
|
|
118
|
+
- `random` selects uniformly without replacement from the complete set of
|
|
119
|
+
synchronized IDs.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
euler-inference -c config.json --sample 250 --sample-mode sequential
|
|
123
|
+
euler-inference -c config.json --sample 0.05 --sample-mode random
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Model contract
|
|
127
|
+
|
|
128
|
+
The external file must define `Model` with these methods:
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
class Model:
|
|
132
|
+
def __init__(self, config: dict, device: str | None = None): ...
|
|
133
|
+
def predict(self, inputs: dict) -> dict: ...
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
- `config` is `external_model.model_config`, or `{}` when omitted.
|
|
137
|
+
- `inputs` contains every regular and hierarchical modality by its configured
|
|
138
|
+
name. Loader metadata determines each value's type.
|
|
139
|
+
- `predict()` runs once per sample and returns a dict keyed by configured
|
|
140
|
+
output names.
|
|
141
|
+
- The model runs in the current process, so its dependencies must be installed
|
|
142
|
+
in the active environment.
|
|
143
|
+
|
|
144
|
+
Models may declare two optional class attributes:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
class Model:
|
|
148
|
+
OUTPUTS = [{"key": "depth", "type": "npy"}]
|
|
149
|
+
DEFAULT_CONFIG = {"backbone": "resnet50"}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
User-provided model config takes precedence over `DEFAULT_CONFIG`. Explicit
|
|
153
|
+
config `outputs` take precedence over `OUTPUTS`.
|
|
154
|
+
|
|
155
|
+
## Configuration
|
|
156
|
+
|
|
157
|
+
The complete monolithic example lives at
|
|
158
|
+
[`configs/example_external_model.json`](configs/example_external_model.json).
|
|
159
|
+
|
|
160
|
+
| Key | Required | Description |
|
|
161
|
+
| --- | --- | --- |
|
|
162
|
+
| `external_model.model_path` | yes | Absolute path to the Python model file |
|
|
163
|
+
| `external_model.model_config` | no | Dict or path to a JSON object passed to `Model` |
|
|
164
|
+
| `dataset.modalities` | yes | Named regular modality paths; IDs are intersected |
|
|
165
|
+
| `dataset.hierarchical_modalities` | no | Named values inherited down a dataset hierarchy |
|
|
166
|
+
| `output_base_path` | yes | Root for prediction datasets |
|
|
167
|
+
| `outputs` | no | Output keys, formats, and writer settings |
|
|
168
|
+
| `device` | no | `cpu`, `cuda`, or `mps`; passed through to the model |
|
|
169
|
+
| `sample` | no | Integer count or fractional dataset size |
|
|
170
|
+
| `sample_mode` | no | `sequential` or `random` |
|
|
171
|
+
| `zip` | no | Write each output as a zip dataset |
|
|
172
|
+
| `strict` | no | Require known modality metadata; default `true` |
|
|
173
|
+
|
|
174
|
+
A modality can be a path string or a structured entry:
|
|
175
|
+
|
|
176
|
+
```json
|
|
177
|
+
{
|
|
178
|
+
"dataset": {
|
|
179
|
+
"modalities": {
|
|
180
|
+
"rgb": "/data/rgb",
|
|
181
|
+
"depth": {"path": "/data/depth", "split": "test"},
|
|
182
|
+
"image": {
|
|
183
|
+
"path": "/data/multi-modal.zip",
|
|
184
|
+
"metadata_scope": "rgb",
|
|
185
|
+
"modality_key": "rgb"
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`split` selects an inline ds-crawler split. `metadata_scope` disambiguates
|
|
193
|
+
multiple indexed modalities at the same physical path; in deterministic cases
|
|
194
|
+
it is inferred from the input name or `modality_key`.
|
|
195
|
+
|
|
196
|
+
### Outputs
|
|
197
|
+
|
|
198
|
+
Each output accepts `key`, `type`, optional `suffix`, optional writer metadata,
|
|
199
|
+
optional `source_modality`, and optional `source_grid`:
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"outputs": [
|
|
204
|
+
{"key": "rgb", "type": "png"},
|
|
205
|
+
{
|
|
206
|
+
"key": "depth",
|
|
207
|
+
"type": "npy",
|
|
208
|
+
"writer": {
|
|
209
|
+
"euler_loading": {
|
|
210
|
+
"loader": "generic_dense_depth",
|
|
211
|
+
"function": "depth"
|
|
212
|
+
},
|
|
213
|
+
"meta": {"radial_depth": false, "scale_to_meters": 1.0}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
]
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
When an output key matches an input modality—or `source_modality` names
|
|
221
|
+
one—the source writer and relative filename are mirrored. Otherwise the legacy
|
|
222
|
+
serializer writes `{sample_id}{suffix}.{type}` beneath the sample hierarchy.
|
|
223
|
+
Supported legacy formats are `npy`, `npz`, `png`, `jpg`, `jpeg`, and `exr`.
|
|
224
|
+
|
|
225
|
+
### How an output relates to its input (`source_grid`)
|
|
226
|
+
|
|
227
|
+
A model that crops or resizes its input returns an output on another pixel
|
|
228
|
+
grid than the image it came from. The shapes alone cannot tell whether a
|
|
229
|
+
400×872 depth map is the top-left of a 400×879 input or a squeezed copy of
|
|
230
|
+
it, so declare it per output:
|
|
231
|
+
|
|
232
|
+
```python
|
|
233
|
+
class Model:
|
|
234
|
+
OUTPUTS = [{"key": "depth", "type": "npy", "source_grid": "crop_top_left"}]
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
| `source_grid` | The output is |
|
|
238
|
+
|---|---|
|
|
239
|
+
| `"identity"` | on the input's grid (sizes must match) |
|
|
240
|
+
| `"resize"` | the whole input stretched to the output size |
|
|
241
|
+
| `"crop_top_left"` | the top-left part of the input, e.g. a latent model that floors each side to a multiple of 8 |
|
|
242
|
+
| `"crop_center"` | the centred part of the input |
|
|
243
|
+
|
|
244
|
+
The input defaults to `source_modality`, else the only regular modality, else
|
|
245
|
+
the only RGB one; name it with `{"rule": "resize", "source": "rgb"}`
|
|
246
|
+
otherwise. For every sample, euler-inference turns the rule and the actual
|
|
247
|
+
input and output sizes into euler-dataset-contract's exact `source_grid`
|
|
248
|
+
(source size plus affine pixel mapping) and writes it to that file's
|
|
249
|
+
attributes. When every sample gets the same one, it also goes into the
|
|
250
|
+
output's dataset head (`modality.meta.source_grid`). euler-eval reads it to
|
|
251
|
+
score the prediction on the right pixels. An output whose size differs from
|
|
252
|
+
its input's without a declared rule logs a warning, and evaluation falls back
|
|
253
|
+
to guessing. Recording needs euler-dataset-contract with `source_grid`
|
|
254
|
+
support.
|
|
255
|
+
|
|
256
|
+
#### Known limitation: mappings the sizes do not determine
|
|
257
|
+
|
|
258
|
+
A rule turns into an exact mapping only because the input and output sizes
|
|
259
|
+
pin it down. Some preprocessing does not leave enough in the sizes:
|
|
260
|
+
|
|
261
|
+
- a resize to an intermediate size followed by a crop, such as
|
|
262
|
+
Depth-Anything-3's `upper_bound_crop` / `lower_bound_crop` (resize the long
|
|
263
|
+
or short side to `process_res`, then centre-crop each side down to a
|
|
264
|
+
multiple of 14); the intermediate size cannot be recovered from the input
|
|
265
|
+
and output sizes in general;
|
|
266
|
+
- letterboxing or padding to a fixed size;
|
|
267
|
+
- crops whose position depends on the content or on randomness.
|
|
268
|
+
|
|
269
|
+
None of the four rules describes these, and declaring the nearest one
|
|
270
|
+
records a wrong mapping. Until models can report it themselves, either make
|
|
271
|
+
such an output land on a rule-describable grid (resize or pad it back onto
|
|
272
|
+
the input grid and declare `identity`, or pick a preprocessing mode that is
|
|
273
|
+
a plain resize, like Depth-Anything-3's default `upper_bound_resize`), or
|
|
274
|
+
declare no `source_grid` and set euler-eval's `spatial_alignment` by hand.
|
|
275
|
+
|
|
276
|
+
**Open design question (deferred):** let a model return the exact
|
|
277
|
+
`source_grid` matrix per sample, which euler-dataset-contract can already
|
|
278
|
+
store. That needs a channel in the model contract, for example an optional
|
|
279
|
+
reserved `"source_grid"` key in `predict()`'s result mapping output keys to
|
|
280
|
+
matrices, or an optional `Model.source_grid(inputs, outputs)` method.
|
|
281
|
+
Either way euler-inference would validate the matrix
|
|
282
|
+
(`euler_dataset_contract.validate_source_grid`) and record it exactly as it
|
|
283
|
+
records rule-derived ones.
|
|
284
|
+
|
|
285
|
+
## Model cards
|
|
286
|
+
|
|
287
|
+
A model card keeps model-owned metadata beside the model and leaves paths to
|
|
288
|
+
the operator. Placeholders use `{{type:name}}` syntax:
|
|
289
|
+
|
|
290
|
+
```json
|
|
291
|
+
{
|
|
292
|
+
"model": "./model.py",
|
|
293
|
+
"checkpoint": "{{checkpoint:weights}}",
|
|
294
|
+
"inputs": {"rgb": "{{modality:rgb}}"},
|
|
295
|
+
"outputs": [{"key": "depth", "type": "npy"}],
|
|
296
|
+
"sample": 100,
|
|
297
|
+
"sample_mode": "random"
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
```bash
|
|
302
|
+
euler-inference \
|
|
303
|
+
--model-card model_card.json \
|
|
304
|
+
--set weights=/models/weights.pt \
|
|
305
|
+
--data rgb=/data/rgb \
|
|
306
|
+
--output-base-path /data/predictions
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Use `--hierarchical-data name=/path` for hierarchical placeholders. See
|
|
310
|
+
[`examples/model_card.json`](examples/model_card.json) and
|
|
311
|
+
[`examples/model_template.py`](examples/model_template.py) for a complete pair.
|
|
312
|
+
|
|
313
|
+
## Python API
|
|
314
|
+
|
|
315
|
+
```python
|
|
316
|
+
from euler_inference.api import infer
|
|
317
|
+
|
|
318
|
+
infer(
|
|
319
|
+
model_path="/absolute/path/to/model.py",
|
|
320
|
+
dataset_modalities={"rgb": "/data/rgb"},
|
|
321
|
+
output_base_path="/data/predictions",
|
|
322
|
+
sample=0.1,
|
|
323
|
+
sample_mode="random",
|
|
324
|
+
)
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
`infer()` also accepts `model_card=`, `bindings=`, `data=`, and
|
|
328
|
+
`hierarchical_data=`. For scheduler-managed output targets, construct an
|
|
329
|
+
`InferenceConfig` with `PipelineRuntimeConfig` and call `run_inference()`.
|
|
330
|
+
|
|
331
|
+
## Development
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
git clone https://github.com/d-rothen/euler-inference.git
|
|
335
|
+
cd euler-inference
|
|
336
|
+
uv sync --extra dev
|
|
337
|
+
uv run pytest -q
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
The unit suite uses synthetic datasets and does not require model weights or a
|
|
341
|
+
GPU. Contributions should keep the model boundary modality-agnostic and add a
|
|
342
|
+
focused regression test for behavior changes.
|
|
343
|
+
|
|
344
|
+
The VKITTI2 integration checks are opt-in:
|
|
345
|
+
|
|
346
|
+
```bash
|
|
347
|
+
VKITTI2_RGB_PATH=/data/vkitti2/rgb \
|
|
348
|
+
VKITTI2_TEXTGT_PATH=/data/vkitti2/textgt \
|
|
349
|
+
uv run pytest -m real
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
## Common integration mistakes
|
|
353
|
+
|
|
354
|
+
- `model_path` in a monolithic config must be absolute.
|
|
355
|
+
- Output keys returned by `predict()` must match configured `outputs[].key`.
|
|
356
|
+
- Relative imports in dynamically loaded model files are fragile; add the
|
|
357
|
+
model directory to `sys.path` or package the model code.
|
|
358
|
+
- Explicit `source_modality` values must name a regular input with a resolvable
|
|
359
|
+
euler-loading writer.
|
|
360
|
+
- A model that crops or resizes its input without declaring `source_grid`
|
|
361
|
+
leaves evaluation to guess which one it did.
|
|
@@ -0,0 +1,342 @@
|
|
|
1
|
+
<!-- euler header — shared across the euler packages.
|
|
2
|
+
Per package, change only: the <h1>, the tagline, and the badge URLs. -->
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="https://files.chronodle.com/icons/euler.svg" alt="euler" width="96" height="96">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">euler-inference</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<em>A small, modality-agnostic runner for applying Python models to indexed datasets.</em>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://pypi.org/project/euler-inference/"><img alt="PyPI" src="https://img.shields.io/pypi/v/euler-inference?color=0A7BBB"></a>
|
|
15
|
+
<a href="https://www.python.org/"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
|
|
16
|
+
</p>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
`euler-inference` connects an in-process model to one or more
|
|
21
|
+
[`euler-loading`](https://github.com/d-rothen/euler-loading) modalities. It
|
|
22
|
+
intersects their dataset IDs, loads synchronized samples, runs `predict()`, and
|
|
23
|
+
writes indexed outputs while preserving source paths when possible.
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
indexed modalities → euler-loading → Model.predict(inputs) → indexed outputs
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
30
|
+
|
|
31
|
+
Install the package:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install euler-inference
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Create a model file. The pipeline deliberately keeps the contract tiny:
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
# /absolute/path/to/model.py
|
|
41
|
+
import numpy as np
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class Model:
|
|
45
|
+
OUTPUTS = [{"key": "depth", "type": "npy"}]
|
|
46
|
+
|
|
47
|
+
def __init__(self, config: dict, device: str | None = None):
|
|
48
|
+
self.scale = config.get("scale", 1.0)
|
|
49
|
+
|
|
50
|
+
def predict(self, inputs: dict) -> dict:
|
|
51
|
+
height, width = inputs["rgb"].shape[-2:]
|
|
52
|
+
depth = np.ones((height, width), dtype=np.float32) * self.scale
|
|
53
|
+
return {"depth": depth}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Point a config at the model and an indexed modality:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"external_model": {
|
|
61
|
+
"model_path": "/absolute/path/to/model.py",
|
|
62
|
+
"model_config": {"scale": 2.0}
|
|
63
|
+
},
|
|
64
|
+
"dataset": {
|
|
65
|
+
"modalities": {"rgb": "/data/vkitti2/rgb"}
|
|
66
|
+
},
|
|
67
|
+
"output_base_path": "/data/predictions",
|
|
68
|
+
"sample": 0.1,
|
|
69
|
+
"sample_mode": "random"
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Run it:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
euler-inference --config config.json
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The dataset directories or zip archives must contain `ds-crawler` metadata.
|
|
80
|
+
`euler-loading` resolves each loader from that metadata, so the model receives
|
|
81
|
+
the native loaded value: for example a NumPy array or torch tensor.
|
|
82
|
+
|
|
83
|
+
## Sampling
|
|
84
|
+
|
|
85
|
+
`sample` limits work before any files are loaded:
|
|
86
|
+
|
|
87
|
+
| Value | Meaning |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| omitted | Process every synchronized dataset ID |
|
|
90
|
+
| integer greater than `1` | Process at most that many IDs |
|
|
91
|
+
| float between `0` and `1` | Process that fraction of all IDs |
|
|
92
|
+
|
|
93
|
+
Fractional counts round down, with a minimum of one sample for a non-empty
|
|
94
|
+
dataset. Counts larger than the dataset are capped at its size.
|
|
95
|
+
|
|
96
|
+
`sample_mode` controls which IDs are chosen:
|
|
97
|
+
|
|
98
|
+
- `sequential` (default) selects the first IDs in dataset order.
|
|
99
|
+
- `random` selects uniformly without replacement from the complete set of
|
|
100
|
+
synchronized IDs.
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
euler-inference -c config.json --sample 250 --sample-mode sequential
|
|
104
|
+
euler-inference -c config.json --sample 0.05 --sample-mode random
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Model contract
|
|
108
|
+
|
|
109
|
+
The external file must define `Model` with these methods:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
class Model:
|
|
113
|
+
def __init__(self, config: dict, device: str | None = None): ...
|
|
114
|
+
def predict(self, inputs: dict) -> dict: ...
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- `config` is `external_model.model_config`, or `{}` when omitted.
|
|
118
|
+
- `inputs` contains every regular and hierarchical modality by its configured
|
|
119
|
+
name. Loader metadata determines each value's type.
|
|
120
|
+
- `predict()` runs once per sample and returns a dict keyed by configured
|
|
121
|
+
output names.
|
|
122
|
+
- The model runs in the current process, so its dependencies must be installed
|
|
123
|
+
in the active environment.
|
|
124
|
+
|
|
125
|
+
Models may declare two optional class attributes:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
class Model:
|
|
129
|
+
OUTPUTS = [{"key": "depth", "type": "npy"}]
|
|
130
|
+
DEFAULT_CONFIG = {"backbone": "resnet50"}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
User-provided model config takes precedence over `DEFAULT_CONFIG`. Explicit
|
|
134
|
+
config `outputs` take precedence over `OUTPUTS`.
|
|
135
|
+
|
|
136
|
+
## Configuration
|
|
137
|
+
|
|
138
|
+
The complete monolithic example lives at
|
|
139
|
+
[`configs/example_external_model.json`](configs/example_external_model.json).
|
|
140
|
+
|
|
141
|
+
| Key | Required | Description |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| `external_model.model_path` | yes | Absolute path to the Python model file |
|
|
144
|
+
| `external_model.model_config` | no | Dict or path to a JSON object passed to `Model` |
|
|
145
|
+
| `dataset.modalities` | yes | Named regular modality paths; IDs are intersected |
|
|
146
|
+
| `dataset.hierarchical_modalities` | no | Named values inherited down a dataset hierarchy |
|
|
147
|
+
| `output_base_path` | yes | Root for prediction datasets |
|
|
148
|
+
| `outputs` | no | Output keys, formats, and writer settings |
|
|
149
|
+
| `device` | no | `cpu`, `cuda`, or `mps`; passed through to the model |
|
|
150
|
+
| `sample` | no | Integer count or fractional dataset size |
|
|
151
|
+
| `sample_mode` | no | `sequential` or `random` |
|
|
152
|
+
| `zip` | no | Write each output as a zip dataset |
|
|
153
|
+
| `strict` | no | Require known modality metadata; default `true` |
|
|
154
|
+
|
|
155
|
+
A modality can be a path string or a structured entry:
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"dataset": {
|
|
160
|
+
"modalities": {
|
|
161
|
+
"rgb": "/data/rgb",
|
|
162
|
+
"depth": {"path": "/data/depth", "split": "test"},
|
|
163
|
+
"image": {
|
|
164
|
+
"path": "/data/multi-modal.zip",
|
|
165
|
+
"metadata_scope": "rgb",
|
|
166
|
+
"modality_key": "rgb"
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`split` selects an inline ds-crawler split. `metadata_scope` disambiguates
|
|
174
|
+
multiple indexed modalities at the same physical path; in deterministic cases
|
|
175
|
+
it is inferred from the input name or `modality_key`.
|
|
176
|
+
|
|
177
|
+
### Outputs
|
|
178
|
+
|
|
179
|
+
Each output accepts `key`, `type`, optional `suffix`, optional writer metadata,
|
|
180
|
+
optional `source_modality`, and optional `source_grid`:
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"outputs": [
|
|
185
|
+
{"key": "rgb", "type": "png"},
|
|
186
|
+
{
|
|
187
|
+
"key": "depth",
|
|
188
|
+
"type": "npy",
|
|
189
|
+
"writer": {
|
|
190
|
+
"euler_loading": {
|
|
191
|
+
"loader": "generic_dense_depth",
|
|
192
|
+
"function": "depth"
|
|
193
|
+
},
|
|
194
|
+
"meta": {"radial_depth": false, "scale_to_meters": 1.0}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
]
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
When an output key matches an input modality—or `source_modality` names
|
|
202
|
+
one—the source writer and relative filename are mirrored. Otherwise the legacy
|
|
203
|
+
serializer writes `{sample_id}{suffix}.{type}` beneath the sample hierarchy.
|
|
204
|
+
Supported legacy formats are `npy`, `npz`, `png`, `jpg`, `jpeg`, and `exr`.
|
|
205
|
+
|
|
206
|
+
### How an output relates to its input (`source_grid`)
|
|
207
|
+
|
|
208
|
+
A model that crops or resizes its input returns an output on another pixel
|
|
209
|
+
grid than the image it came from. The shapes alone cannot tell whether a
|
|
210
|
+
400×872 depth map is the top-left of a 400×879 input or a squeezed copy of
|
|
211
|
+
it, so declare it per output:
|
|
212
|
+
|
|
213
|
+
```python
|
|
214
|
+
class Model:
|
|
215
|
+
OUTPUTS = [{"key": "depth", "type": "npy", "source_grid": "crop_top_left"}]
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
| `source_grid` | The output is |
|
|
219
|
+
|---|---|
|
|
220
|
+
| `"identity"` | on the input's grid (sizes must match) |
|
|
221
|
+
| `"resize"` | the whole input stretched to the output size |
|
|
222
|
+
| `"crop_top_left"` | the top-left part of the input, e.g. a latent model that floors each side to a multiple of 8 |
|
|
223
|
+
| `"crop_center"` | the centred part of the input |
|
|
224
|
+
|
|
225
|
+
The input defaults to `source_modality`, else the only regular modality, else
|
|
226
|
+
the only RGB one; name it with `{"rule": "resize", "source": "rgb"}`
|
|
227
|
+
otherwise. For every sample, euler-inference turns the rule and the actual
|
|
228
|
+
input and output sizes into euler-dataset-contract's exact `source_grid`
|
|
229
|
+
(source size plus affine pixel mapping) and writes it to that file's
|
|
230
|
+
attributes. When every sample gets the same one, it also goes into the
|
|
231
|
+
output's dataset head (`modality.meta.source_grid`). euler-eval reads it to
|
|
232
|
+
score the prediction on the right pixels. An output whose size differs from
|
|
233
|
+
its input's without a declared rule logs a warning, and evaluation falls back
|
|
234
|
+
to guessing. Recording needs euler-dataset-contract with `source_grid`
|
|
235
|
+
support.
|
|
236
|
+
|
|
237
|
+
#### Known limitation: mappings the sizes do not determine
|
|
238
|
+
|
|
239
|
+
A rule turns into an exact mapping only because the input and output sizes
|
|
240
|
+
pin it down. Some preprocessing does not leave enough in the sizes:
|
|
241
|
+
|
|
242
|
+
- a resize to an intermediate size followed by a crop, such as
|
|
243
|
+
Depth-Anything-3's `upper_bound_crop` / `lower_bound_crop` (resize the long
|
|
244
|
+
or short side to `process_res`, then centre-crop each side down to a
|
|
245
|
+
multiple of 14); the intermediate size cannot be recovered from the input
|
|
246
|
+
and output sizes in general;
|
|
247
|
+
- letterboxing or padding to a fixed size;
|
|
248
|
+
- crops whose position depends on the content or on randomness.
|
|
249
|
+
|
|
250
|
+
None of the four rules describes these, and declaring the nearest one
|
|
251
|
+
records a wrong mapping. Until models can report it themselves, either make
|
|
252
|
+
such an output land on a rule-describable grid (resize or pad it back onto
|
|
253
|
+
the input grid and declare `identity`, or pick a preprocessing mode that is
|
|
254
|
+
a plain resize, like Depth-Anything-3's default `upper_bound_resize`), or
|
|
255
|
+
declare no `source_grid` and set euler-eval's `spatial_alignment` by hand.
|
|
256
|
+
|
|
257
|
+
**Open design question (deferred):** let a model return the exact
|
|
258
|
+
`source_grid` matrix per sample, which euler-dataset-contract can already
|
|
259
|
+
store. That needs a channel in the model contract, for example an optional
|
|
260
|
+
reserved `"source_grid"` key in `predict()`'s result mapping output keys to
|
|
261
|
+
matrices, or an optional `Model.source_grid(inputs, outputs)` method.
|
|
262
|
+
Either way euler-inference would validate the matrix
|
|
263
|
+
(`euler_dataset_contract.validate_source_grid`) and record it exactly as it
|
|
264
|
+
records rule-derived ones.
|
|
265
|
+
|
|
266
|
+
## Model cards
|
|
267
|
+
|
|
268
|
+
A model card keeps model-owned metadata beside the model and leaves paths to
|
|
269
|
+
the operator. Placeholders use `{{type:name}}` syntax:
|
|
270
|
+
|
|
271
|
+
```json
|
|
272
|
+
{
|
|
273
|
+
"model": "./model.py",
|
|
274
|
+
"checkpoint": "{{checkpoint:weights}}",
|
|
275
|
+
"inputs": {"rgb": "{{modality:rgb}}"},
|
|
276
|
+
"outputs": [{"key": "depth", "type": "npy"}],
|
|
277
|
+
"sample": 100,
|
|
278
|
+
"sample_mode": "random"
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
euler-inference \
|
|
284
|
+
--model-card model_card.json \
|
|
285
|
+
--set weights=/models/weights.pt \
|
|
286
|
+
--data rgb=/data/rgb \
|
|
287
|
+
--output-base-path /data/predictions
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Use `--hierarchical-data name=/path` for hierarchical placeholders. See
|
|
291
|
+
[`examples/model_card.json`](examples/model_card.json) and
|
|
292
|
+
[`examples/model_template.py`](examples/model_template.py) for a complete pair.
|
|
293
|
+
|
|
294
|
+
## Python API
|
|
295
|
+
|
|
296
|
+
```python
|
|
297
|
+
from euler_inference.api import infer
|
|
298
|
+
|
|
299
|
+
infer(
|
|
300
|
+
model_path="/absolute/path/to/model.py",
|
|
301
|
+
dataset_modalities={"rgb": "/data/rgb"},
|
|
302
|
+
output_base_path="/data/predictions",
|
|
303
|
+
sample=0.1,
|
|
304
|
+
sample_mode="random",
|
|
305
|
+
)
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
`infer()` also accepts `model_card=`, `bindings=`, `data=`, and
|
|
309
|
+
`hierarchical_data=`. For scheduler-managed output targets, construct an
|
|
310
|
+
`InferenceConfig` with `PipelineRuntimeConfig` and call `run_inference()`.
|
|
311
|
+
|
|
312
|
+
## Development
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
git clone https://github.com/d-rothen/euler-inference.git
|
|
316
|
+
cd euler-inference
|
|
317
|
+
uv sync --extra dev
|
|
318
|
+
uv run pytest -q
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
The unit suite uses synthetic datasets and does not require model weights or a
|
|
322
|
+
GPU. Contributions should keep the model boundary modality-agnostic and add a
|
|
323
|
+
focused regression test for behavior changes.
|
|
324
|
+
|
|
325
|
+
The VKITTI2 integration checks are opt-in:
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
VKITTI2_RGB_PATH=/data/vkitti2/rgb \
|
|
329
|
+
VKITTI2_TEXTGT_PATH=/data/vkitti2/textgt \
|
|
330
|
+
uv run pytest -m real
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
## Common integration mistakes
|
|
334
|
+
|
|
335
|
+
- `model_path` in a monolithic config must be absolute.
|
|
336
|
+
- Output keys returned by `predict()` must match configured `outputs[].key`.
|
|
337
|
+
- Relative imports in dynamically loaded model files are fragile; add the
|
|
338
|
+
model directory to `sys.path` or package the model code.
|
|
339
|
+
- Explicit `source_modality` values must name a regular input with a resolvable
|
|
340
|
+
euler-loading writer.
|
|
341
|
+
- A model that crops or resizes its input without declaring `source_grid`
|
|
342
|
+
leaves evaluation to guess which one it did.
|