iolabs-common (shared config layer) b9e3427: AI3D-382 Document the extra-key policy of the point-record helpers

Miroslav Simko <ms@iolabs.ch> 2026-09-01T23:39:27+02:00

Commit #90 · 4 snippets

 src/iolabs/common/segment_points_io.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

AI3D-382 (number_of_returns through the run3 NPZ contract). Unrelated to the config migration; already released and pushed. Included because it falls in the time window.

     boolean) dtype cannot leak downstream and break a mixed-vintage
     concatenation. The returned mapping always holds every key in
     :data:`POINT_RECORD_KEYS`, in registry order.
+    Extra-key policy: NPZ members outside the schema are ignored, so the
+    returned record carries exactly :data:`POINT_RECORD_KEYS` and nothing a
+    hand-rolled producer may have added alongside them.
     Raises:
         ValueError: A required key is missing, an array has the wrong shape, or
             a member with a declared storage dtype is stored with a
             non-integer/bool dtype or values outside that dtype's range.

     raises instead of zero-filling. Members whose spec declares a storage dtype
     (``number_of_returns``: uint8) are coerced to it before the write; the rest
     are stored with the dtype the producer supplied.
+    Extra-key policy: only the schema keys are written, so any extra key the
+    record carries -- including one :func:`mask_record` or
+    :func:`concat_records` passed through -- is silently dropped by the write.
     Raises:
         ValueError: A key is missing, an array has the wrong shape, or a member
             with a declared storage dtype cannot be cast to it losslessly.
     """

     *mask* along axis 0, so ``points`` keeps its ``(n, 3)`` rows while the
     ancillary members stay 1-D. Adding a field to the contract needs no change
     here.
+    Extra-key policy: keys outside the schema are masked and returned like any
+    other, but :func:`save_points_npz` writes only schema keys, so an extra key
+    survives in memory and is lost by a later save.
     Args:
         record: Point record whose members all share a leading dimension.
         mask: Boolean mask of shape ``(N,)`` or an integer index array; any
             NumPy row indexer works.

     Schema-agnostic: every key of the first record is concatenated across all
     records, so ``points`` grows by rows and the ancillary members by elements.
     Dtypes are not checked here -- :func:`concat_points_npz` owns that policy.
+    Extra-key policy: keys outside the schema are concatenated and returned
+    like any other, but :func:`save_points_npz` writes only schema keys, so an
+    extra key survives in memory and is lost by a later save.
     Args:
         records: Records to join, in the intended order. All must carry the
             same key set.