euler-loading 2.25.0__tar.gz → 2.26.0__tar.gz

{euler_loading-2.25.0 → euler_loading-2.26.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+- Add `read_extrinsics` to the Synscapes loaders, building a 4x4 rigid
+  transform from the six `camera.extrinsic` scalars. `transform_direction`
+  and `camera_axes` select the pose, its inverse, and vehicle or optical
+  camera axes; the assumed `Rz(yaw) @ Ry(pitch) @ Rx(roll)` order is recorded
+  in the modality metadata because the dataset does not document it.
+- Add Synscapes writers for every modality, making the loader a
+  `DenseDepthCodec`. Depth writes a float32 EXR `Z` channel and needs a
+  filesystem path; the intrinsics and extrinsics writers merge into a single
+  `meta/<id>.json`, replacing it in one step and keeping its permissions,
+  symlink and unmodelled fields rather than truncating it in place.
+- `sky_mask` now honours `meta['sky_class_id']`, or the same key in per-file
+  attributes, instead of hardcoding Cityscapes ID 23, so a dataset that
+  relabels sky round-trips through `write_sky_mask`.
+- Accept the plural `camera.intrinsics` / `camera.extrinsics` spellings and
+  report missing camera fields by name instead of raising `KeyError`.
+
 ## 2.24.0 (unreleased)
 
 Add source-backed capture, strict per-output writers, explicit NPY/PNG encoding, typed calibration views and replay. Consolidate pinhole geometry and correct legacy skew scaling.

{euler_loading-2.25.0 → euler_loading-2.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: euler-loading
-Version: 2.25.0
+Version: 2.26.0
 Summary: Multi-modal PyTorch dataloader using ds-crawler indices
 Project-URL: Homepage, https://github.com/d-rothen/euler-loading
 Project-URL: Repository, https://github.com/d-rothen/euler-loading

{euler_loading-2.25.0 → euler_loading-2.26.0}/docs/loaders.md

@@ -193,8 +193,26 @@ Writers exist for every modality above.
 | `depth` | 1HW / HW | float32 | `img/depth/<id>.exr`, `Z` channel, planar depth in metres |
 | `class_segmentation` | 1HW / HW | int64 | `img/class/<id>.png`, original Cityscapes label IDs |
 | `instance_segmentation` | 1HW / HW | int64 | `img/instance/<id>.png`, decoded as `R + 256 * G + 65536 * B` |
-| `sky_mask` | 1HW / HW | bool | Sky label ID `23` in `img/class/<id>.png` |
+| `sky_mask` | 1HW / HW | bool | Sky label in `img/class/<id>.png`; ID `23` by default, or `meta['sky_class_id']` |
 | `read_intrinsics` | 3×3 | float32 | `camera.intrinsic` from `meta/<id>.json`: `fx`, `fy`, `u0`, `v0` |
+| `read_extrinsics` | 4×4 | float32 | `camera.extrinsic` from `meta/<id>.json`: `x`, `y`, `z`, `pitch`, `roll`, `yaw` |
+
+Writers exist for every modality above. `write_depth` needs a filesystem path
+because OpenEXR cannot write to a stream; dataset writers hand it a temporary
+file automatically, so zip outputs work unchanged. `write_sky_mask` emits a
+class image labelling sky with `meta['sky_class_id']`, default 23, and
+`write_intrinsics` and `write_extrinsics` merge into one `meta/<id>.json`
+rather than overwriting each other or the file's `scene` and `instance`
+blocks.
+
+That merge reads the file back, so it applies to filesystem destinations and
+replaces the file atomically. A zip destination is handed a fresh stream per
+modality instead, so writing both camera modalities into the **same** archive
+produces two entries with the same name, of which only the last is
+retrievable — give each modality its own output writer. Because the merge
+keeps fields it does not model, writing a rescaled matrix without passing
+`meta['resx']`/`['resy']` leaves the previous resolution in place; supply them
+whenever the matrix no longer matches the recorded resolution.
 
 Formats follow the [Synscapes dataset reference](https://synscapes.on.liu.se/features.html)
 and [FoggySynscapes EXR reader](https://github.com/MartinHahner/FoggySynscapes/blob/main/source/Depth_processing/exr_to_mat.py).
@@ -202,14 +220,14 @@ Depth values are already in metres, so they are returned unchanged, including
 non-finite values. Semantic labels retain the original IDs, including void
 labels, without remapping to training IDs.
 
-EXR loading needs the optional OpenEXR dependency:
+EXR depth loading and writing need the optional OpenEXR dependency:
 
 ```bash
 pip install "euler-loading[gpu,synscapes]"  # omit gpu for NumPy-only use
 ```
 
-RGB, segmentation and intrinsics work without OpenEXR. All six functions
-accept paths and binary streams. Intrinsics are stored in per-image files,
+RGB, segmentation, intrinsics and extrinsics work without OpenEXR; only depth
+loading and writing need it. All readers accept paths and binary streams. Intrinsics are stored in per-image files,
 so the native `meta` directory is a regular modality:
 
 ```python
@@ -224,6 +242,37 @@ dataset = MultiModalDataset(modalities={
 })
 ```
 
+#### Extrinsics conventions
+
+Synscapes records the camera mount as six scalars — `x`, `y`, `z` in metres and
+`pitch`, `roll`, `yaw` in radians — in the ego-vehicle frame, which the dataset
+defines as x forward, y left, z up. `read_extrinsics` composes them into a
+rigid 4×4 matrix, by default the camera's pose on the vehicle
+(`X_ego = T @ X_camera`). Two keys, taken from per-file `attributes` first and
+then from `meta`, select the other useful conventions:
+
+| Key | Values | Meaning |
+|---|---|---|
+| `transform_direction` | `camera_to_ego` (default), `ego_to_camera` | Direction of the returned transform |
+| `camera_axes` | `vehicle` (default), `optical` | Camera axes: vehicle-aligned, or x right / y down / z forward |
+
+Combine `ego_to_camera` with `optical` to project ego-frame points — such as
+the 3D bounding boxes in the instance metadata — through `read_intrinsics`:
+
+```python
+T = synscapes.read_extrinsics(
+    "/data/Synscapes/meta/1.json",
+    {"transform_direction": "ego_to_camera", "camera_axes": "optical"},
+)
+```
+
+The dataset documents the six fields and the ego frame but not the order in
+which the angles compose, so the loaders apply the usual automotive
+`Rz(yaw) @ Ry(pitch) @ Rx(roll)` and record that in `loaders.json` under the
+modality's `rotation_order`. The values are constant across the released
+dataset. `write_extrinsics` reads the same two keys, so a matrix loaded with
+one set of options writes back unchanged with the same options.
+
 Automatic resolution uses `loader="synscapes"` in the dataset contract.
 Intrinsics describe the metadata's image resolution (native 1440×720).
 When using `img/rgb-2k` at 2048×1024, scale the camera matrix with