fix(io): skip unknown CBOR keys in image, mesh, and transform IO for forward compatibility

thewtex · thewtex · commit a59552778418 · 2026-02-17T11:24:20.000-05:00
Replace itkExceptionMacro throws with silent skips for unrecognized
CBOR map keys in ReadCBOR across all three IO classes:

- itkWasmImageIO: imageType inner sub-map (top-level was already fixed)
- itkWasmMeshIO: meshType inner sub-map + explicit top-level else clause
- itkWasmTransformIO: transformType inner sub-map + explicit top-level else clause

This improves interoperability with third-party CBOR writers (e.g. NiiVue)
that may include additional or extended fields in the type sub-maps.

Also replace empty test stubs in transform-io with real round-trip tests
for wasm-zstd and MNC (.xfm) formats, using programmatically created
affine transforms to avoid dependency on IPFS test data downloads.
diff --git a/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_mnc_read_transform.py b/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_mnc_read_transform.py
@@ -1,8 +1,51 @@
-# Generated file. To retain edits, remove this comment.
+import numpy as np
 
-from itkwasm_transform_io_wasi import mnc_read_transform
+from itkwasm import Transform, TransformParameterizations, FloatTypes
+from itkwasm_transform_io_wasi import mnc_read_transform, mnc_write_transform
+
+from .common import test_output_path, verify_test_linear_transform
+
+
+def _make_affine_transform():
+    """Create an affine transform matching the LinearTransform test fixture."""
+    return Transform(
+        transformType={
+            "transformParameterization": TransformParameterizations.Affine,
+            "parametersValueType": FloatTypes.Float64,
+            "inputDimension": 3,
+            "outputDimension": 3,
+        },
+        numberOfFixedParameters=3,
+        numberOfParameters=12,
+        fixedParameters=np.array([0.0, 0.0, 0.0]),
+        parameters=np.array(
+            [
+                0.65631490118447,
+                0.5806583745824385,
+                -0.4817536741017158,
+                -0.7407986817430222,
+                0.37486398378429736,
+                -0.5573995934598175,
+                -0.14306664045479867,
+                0.7227121458012518,
+                0.676179776908723,
+                -65.99999999999997,
+                69.00000000000004,
+                32.000000000000036,
+            ]
+        ),
+    )
 
-from .common import test_input_path, test_output_path
 
 def test_mnc_read_transform():
-    pass
+    """Test reading an MNC (.xfm) transform file."""
+    transform = _make_affine_transform()
+    transform_list = [transform]
+
+    xfm_path = test_output_path / "mnc-read-test-LinearTransform.xfm"
+    could_write = mnc_write_transform(transform_list, str(xfm_path))
+    assert could_write
+
+    could_read, transform_list_back = mnc_read_transform(xfm_path)
+    assert could_read
+    verify_test_linear_transform(transform_list_back)
diff --git a/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_mnc_write_transform.py b/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_mnc_write_transform.py
@@ -1,8 +1,61 @@
-# Generated file. To retain edits, remove this comment.
+import numpy as np
 
-from itkwasm_transform_io_wasi import mnc_write_transform
+from itkwasm import Transform, TransformParameterizations, FloatTypes
+from itkwasm_transform_io_wasi import mnc_read_transform, mnc_write_transform
+
+from .common import test_output_path, verify_test_linear_transform
+
+
+def _make_affine_transform():
+    """Create an affine transform matching the LinearTransform test fixture."""
+    return Transform(
+        transformType={
+            "transformParameterization": TransformParameterizations.Affine,
+            "parametersValueType": FloatTypes.Float64,
+            "inputDimension": 3,
+            "outputDimension": 3,
+        },
+        numberOfFixedParameters=3,
+        numberOfParameters=12,
+        fixedParameters=np.array([0.0, 0.0, 0.0]),
+        parameters=np.array(
+            [
+                0.65631490118447,
+                0.5806583745824385,
+                -0.4817536741017158,
+                -0.7407986817430222,
+                0.37486398378429736,
+                -0.5573995934598175,
+                -0.14306664045479867,
+                0.7227121458012518,
+                0.676179776908723,
+                -65.99999999999997,
+                69.00000000000004,
+                32.000000000000036,
+            ]
+        ),
+    )
 
-from .common import test_input_path, test_output_path
 
 def test_mnc_write_transform():
-    pass
+    """Test writing an MNC (.xfm) transform and reading it back."""
+    transform = _make_affine_transform()
+    transform_list = [transform]
+
+    xfm_path = test_output_path / "mnc-write-test-LinearTransform.xfm"
+    could_write = mnc_write_transform(transform_list, str(xfm_path))
+    assert could_write
+
+    could_read, transform_list_back = mnc_read_transform(xfm_path)
+    assert could_read
+    verify_test_linear_transform(transform_list_back)
+
+    # Verify exact parameter values survive the round-trip
+    np.testing.assert_allclose(
+        transform_list_back[0].parameters,
+        transform.parameters,
+    )
+    np.testing.assert_allclose(
+        transform_list_back[0].fixedParameters,
+        transform.fixedParameters,
+    )
diff --git a/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_wasm_zstd_read_transform.py b/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_wasm_zstd_read_transform.py
@@ -1,8 +1,54 @@
-# Generated file. To retain edits, remove this comment.
+import numpy as np
 
-from itkwasm_transform_io_wasi import wasm_zstd_read_transform
+from itkwasm import Transform, TransformParameterizations, FloatTypes
+from itkwasm_transform_io_wasi import (
+    wasm_zstd_read_transform,
+    wasm_zstd_write_transform,
+)
+
+from .common import test_output_path, verify_test_linear_transform
+
+
+def _make_affine_transform():
+    """Create an affine transform matching the LinearTransform test fixture."""
+    return Transform(
+        transformType={
+            "transformParameterization": TransformParameterizations.Affine,
+            "parametersValueType": FloatTypes.Float64,
+            "inputDimension": 3,
+            "outputDimension": 3,
+        },
+        numberOfFixedParameters=3,
+        numberOfParameters=12,
+        fixedParameters=np.array([0.0, 0.0, 0.0]),
+        parameters=np.array(
+            [
+                0.65631490118447,
+                0.5806583745824385,
+                -0.4817536741017158,
+                -0.7407986817430222,
+                0.37486398378429736,
+                -0.5573995934598175,
+                -0.14306664045479867,
+                0.7227121458012518,
+                0.676179776908723,
+                -65.99999999999997,
+                69.00000000000004,
+                32.000000000000036,
+            ]
+        ),
+    )
 
-from .common import test_input_path, test_output_path
 
 def test_wasm_zstd_read_transform():
-    pass
+    """Test reading a zstd-compressed IWT CBOR transform file."""
+    transform = _make_affine_transform()
+    transform_list = [transform]
+
+    zstd_path = test_output_path / "zstd-read-test-LinearTransform.iwt.cbor.zst"
+    could_write = wasm_zstd_write_transform(transform_list, str(zstd_path))
+    assert could_write
+
+    could_read, transform_list_back = wasm_zstd_read_transform(zstd_path)
+    assert could_read
+    verify_test_linear_transform(transform_list_back)
diff --git a/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_wasm_zstd_write_transform.py b/packages/transform-io/python/itkwasm-transform-io-wasi/tests/test_wasm_zstd_write_transform.py
@@ -1,8 +1,64 @@
-# Generated file. To retain edits, remove this comment.
+import numpy as np
 
-from itkwasm_transform_io_wasi import wasm_zstd_write_transform
+from itkwasm import Transform, TransformParameterizations, FloatTypes
+from itkwasm_transform_io_wasi import (
+    wasm_zstd_read_transform,
+    wasm_zstd_write_transform,
+)
+
+from .common import test_output_path, verify_test_linear_transform
+
+
+def _make_affine_transform():
+    """Create an affine transform matching the LinearTransform test fixture."""
+    return Transform(
+        transformType={
+            "transformParameterization": TransformParameterizations.Affine,
+            "parametersValueType": FloatTypes.Float64,
+            "inputDimension": 3,
+            "outputDimension": 3,
+        },
+        numberOfFixedParameters=3,
+        numberOfParameters=12,
+        fixedParameters=np.array([0.0, 0.0, 0.0]),
+        parameters=np.array(
+            [
+                0.65631490118447,
+                0.5806583745824385,
+                -0.4817536741017158,
+                -0.7407986817430222,
+                0.37486398378429736,
+                -0.5573995934598175,
+                -0.14306664045479867,
+                0.7227121458012518,
+                0.676179776908723,
+                -65.99999999999997,
+                69.00000000000004,
+                32.000000000000036,
+            ]
+        ),
+    )
 
-from .common import test_input_path, test_output_path
 
 def test_wasm_zstd_write_transform():
-    pass
+    """Test writing a zstd-compressed IWT CBOR transform and reading it back."""
+    transform = _make_affine_transform()
+    transform_list = [transform]
+
+    zstd_path = test_output_path / "zstd-write-test-LinearTransform.iwt.cbor.zst"
+    could_write = wasm_zstd_write_transform(transform_list, str(zstd_path))
+    assert could_write
+
+    could_read, transform_list_back = wasm_zstd_read_transform(zstd_path)
+    assert could_read
+    verify_test_linear_transform(transform_list_back)
+
+    # Verify exact parameter values survive the round-trip
+    np.testing.assert_allclose(
+        transform_list_back[0].parameters,
+        transform.parameters,
+    )
+    np.testing.assert_allclose(
+        transform_list_back[0].fixedParameters,
+        transform.fixedParameters,
+    )
diff --git a/src/itkWasmImageIO.cxx b/src/itkWasmImageIO.cxx
@@ -248,7 +248,8 @@ WasmImageIO ::ReadCBOR(void * buffer, unsigned char * cborBuffer, size_t cborBuf
         }
         else
         {
-          itkExceptionMacro("Unexpected imageType cbor map key: " << imageTypeKey);
+          // Skip unknown keys for forward compatibility and interoperability
+          // with third-party CBOR writers that may include additional fields.
         }
       }
     }
diff --git a/src/itkWasmMeshIO.cxx b/src/itkWasmMeshIO.cxx
@@ -234,7 +234,8 @@ WasmMeshIO ::ReadCBOR(void * buffer, unsigned char * cborBuffer, size_t cborBuff
         }
         else
         {
-          itkExceptionMacro("Unexpected meshType cbor map key: " << meshTypeKey);
+          // Skip unknown keys for forward compatibility and interoperability
+          // with third-party CBOR writers that may include additional fields.
         }
       }
     }
@@ -279,6 +280,11 @@ WasmMeshIO ::ReadCBOR(void * buffer, unsigned char * cborBuffer, size_t cborBuff
       const auto components = cbor_get_uint64(indexHandle[ii].value);
       this->SetCellBufferSize(components);
     }
+    else
+    {
+      // Skip unknown keys for forward compatibility and interoperability
+      // with third-party CBOR writers that may include additional fields.
+    }
   }
 }
 
diff --git a/src/itkWasmTransformIO.cxx b/src/itkWasmTransformIO.cxx
@@ -342,7 +342,8 @@ WasmTransformIOTemplate<TParametersValueType>::ReadCBOR(void *          buffer,
           }
           else
           {
-            itkExceptionMacro("Unexpected transformType cbor map key: " << transformTypeKey);
+            // Skip unknown keys for forward compatibility and interoperability
+            // with third-party CBOR writers that may include additional fields.
           }
         }
       }
@@ -374,6 +375,11 @@ WasmTransformIOTemplate<TParametersValueType>::ReadCBOR(void *          buffer,
                                           cbor_string_length(transformHandle[jj].value));
         transformJSON.outputSpaceName = outputSpaceName;
       }
+      else
+      {
+        // Skip unknown keys for forward compatibility and interoperability
+        // with third-party CBOR writers that may include additional fields.
+      }
     }
     transformListJSON.push_back(transformJSON);
   }

Original file line number	Diff line number	Diff line change
`@@ -248,7 +248,8 @@ WasmImageIO ::ReadCBOR(void * buffer, unsigned char * cborBuffer, size_t cborBuf`
`248`	`248`	`}`
`249`	`249`	`else`
`250`	`250`	`{`
`251`		`- itkExceptionMacro("Unexpected imageType cbor map key: " << imageTypeKey);`
	`251`	`+ // Skip unknown keys for forward compatibility and interoperability`
	`252`	`+ // with third-party CBOR writers that may include additional fields.`
`252`	`253`	`}`
`253`	`254`	`}`
`254`	`255`	`}`
Original file line number	Diff line number	Diff line change
`@@ -234,7 +234,8 @@ WasmMeshIO ::ReadCBOR(void * buffer, unsigned char * cborBuffer, size_t cborBuff`
`234`	`234`	`}`
`235`	`235`	`else`
`236`	`236`	`{`
`237`		`- itkExceptionMacro("Unexpected meshType cbor map key: " << meshTypeKey);`
	`237`	`+ // Skip unknown keys for forward compatibility and interoperability`
	`238`	`+ // with third-party CBOR writers that may include additional fields.`
`238`	`239`	`}`
`239`	`240`	`}`
`240`	`241`	`}`
`@@ -279,6 +280,11 @@ WasmMeshIO ::ReadCBOR(void * buffer, unsigned char * cborBuffer, size_t cborBuff`
`279`	`280`	`const auto components = cbor_get_uint64(indexHandle[ii].value);`
`280`	`281`	`this->SetCellBufferSize(components);`
`281`	`282`	`}`
	`283`	`+ else`
	`284`	`+ {`
	`285`	`+ // Skip unknown keys for forward compatibility and interoperability`
	`286`	`+ // with third-party CBOR writers that may include additional fields.`
	`287`	`+ }`
`282`	`288`	`}`
`283`	`289`	`}`
`284`	`290`
Original file line number	Diff line number	Diff line change
`@@ -342,7 +342,8 @@ WasmTransformIOTemplate<TParametersValueType>::ReadCBOR(void * buffer,`
`342`	`342`	`}`
`343`	`343`	`else`
`344`	`344`	`{`
`345`		`- itkExceptionMacro("Unexpected transformType cbor map key: " << transformTypeKey);`
	`345`	`+ // Skip unknown keys for forward compatibility and interoperability`
	`346`	`+ // with third-party CBOR writers that may include additional fields.`
`346`	`347`	`}`
`347`	`348`	`}`
`348`	`349`	`}`
`@@ -374,6 +375,11 @@ WasmTransformIOTemplate<TParametersValueType>::ReadCBOR(void * buffer,`
`374`	`375`	`cbor_string_length(transformHandle[jj].value));`
`375`	`376`	`transformJSON.outputSpaceName = outputSpaceName;`
`376`	`377`	`}`
	`378`	`+ else`
	`379`	`+ {`
	`380`	`+ // Skip unknown keys for forward compatibility and interoperability`
	`381`	`+ // with third-party CBOR writers that may include additional fields.`
	`382`	`+ }`
`377`	`383`	`}`
`378`	`384`	`transformListJSON.push_back(transformJSON);`
`379`	`385`	`}`