feat(data): carry the concrete type inside serialized external distortion parameters

[janickm]

Follow-up to #179, which introduced the ExternalDistortionParameters base but had to leave CameraModelParameters.external_distortion_parameters naming the concrete union. This removes that compromise.

Why the field could not name the abstract base

dataclasses_json reconstructs whatever type a field is annotated with, and the serialized form carried no discriminator: the type was written beside the camera parameters by encode_camera_model_parameters, not inside the nested object. Confirmed directly:

>>> camera.to_dict()["external_distortion_parameters"].keys()
['horizontal_poly', 'horizontal_poly_inverse', 'reference_poly', 'vertical_poly', 'vertical_poly_inverse']

With a single-member union that resolves by luck. Against the abstract base, from_dict builds the base itself, which is a runtime fault rather than a typing one — it surfaced downstream as TypeError: Unsupported external distortion type <class '...ExternalDistortionParameters'>, only at the point of use.

What changes

The serialized form becomes a discriminated union: the concrete type() is written inside the object under EXTERNAL_DISTORTION_TYPE_KEY, and the field's decoder dispatches on it through a registry that out-of-tree parameter types join via register_external_distortion_parameters, mirroring the model-side registry added in #179.

The field is then declared against ExternalDistortionParameters, and the four get_parameters casts name it too.

Compatibility

Both directions hold, and each is covered by a test rather than assumed:

case	behaviour
payload predating the nested key	decodes as bivariate-windshield — unambiguous, it was the only concrete type
previous encoded layout (type beside the camera parameters)	decode_camera_model_parameters migrates it into the nested object
reader predating this change, reading data written by it	still resolves the concrete type: encode_ keeps writing the camera-level type
reader predating this change, seeing the added nested key	ignores it (verified against the published wheel)

The camera-level type is therefore written twice for now. That is deliberate and commented; it can be dropped once no reader predating this change remains, and doing so would be the only breaking step — so it is not taken here.

Scope

This widens a field that callers read, so downstream consumers passing it to concretely-typed APIs need updating in step with the release. The remaining read positions (decode_* return types and the parameter accessors in the compat layers) are deliberately left for a separate change, so this one stays a self-contained format change.

Verified: 33/33 tests on 3.8 and 3.11 with --nocache_test_results, ty aspect clean, //:format.check clean.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.