Added GeomEncoder for JSON deprecating LocationEncoder

Author: gumyr

src/build123d/__init__.py

@@ -150,6 +150,7 @@
     "Compound",
     "Location",
     "LocationEncoder",
+    "GeomEncoder",
     "Joint",
     "RigidJoint",
     "RevoluteJoint",

src/build123d/geometry.py

@@ -39,12 +39,12 @@
 import json
 import logging
 import numpy as np
+import warnings
 
+from collections.abc import Iterable, Sequence
 from math import degrees, pi, radians, isclose
 from typing import Any, overload, TypeAlias, TYPE_CHECKING
 
-from collections.abc import Iterable, Sequence
-
 import OCP.TopAbs as TopAbs_ShapeEnum
 
 from OCP.Bnd import Bnd_Box, Bnd_OBB
@@ -1252,6 +1252,68 @@ def __repr__(self) -> str:
         return f"Color{str(tuple(self))}"
 
 
+class GeomEncoder(json.JSONEncoder):
+    """
+    A JSON encoder for build123d geometry objects.
+
+    This class extends ``json.JSONEncoder`` to provide custom serialization for
+    geometry objects such as Axis, Color, Location, Plane, and Vector. It converts
+    each geometry object into a dictionary containing exactly one key that identifies
+    the geometry type (e.g. ``"Axis"``, ``"Vector"``, etc.), paired with a tuple or
+    list that represents the underlying data. Any other object types are handled by
+    the standard encoder.
+
+    The inverse decoding is performed by the ``geometry_hook`` static method, which
+    expects the dictionary to have precisely one key from the known geometry types.
+    It then uses a class registry (``CLASS_REGISTRY``) to look up and instantiate
+    the appropriate class with the provided values.
+
+    **Usage Example**::
+
+        import json
+
+        # Suppose we have some geometry objects:
+        axis = Axis(position=(0, 0, 0), direction=(1, 0, 0))
+        vector = Vector(0.0, 1.0, 2.0)
+
+        data = {
+            "my_axis": axis,
+            "my_vector": vector
+        }
+
+        # Encode them to JSON:
+        encoded_data = json.dumps(data, cls=GeomEncoder, indent=4)
+
+        # Decode them back:
+        decoded_data = json.loads(encoded_data, object_hook=GeomEncoder.geometry_hook)
+
+    """
+
+    def default(self, obj):
+        """Return a JSON-serializable representation of a known geometry object."""
+        if isinstance(obj, Axis):
+            return {"Axis": (tuple(obj.position), tuple(obj.direction))}
+        elif isinstance(obj, Color):
+            return {"Color": obj.to_tuple()}
+        if isinstance(obj, Location):
+            return {"Location": obj.to_tuple()}
+        elif isinstance(obj, Plane):
+            return {"Plane": (tuple(obj.origin), tuple(obj.x_dir), tuple(obj.z_dir))}
+        elif isinstance(obj, Vector):
+            return {"Vector": tuple(obj)}
+        else:
+            # Let the base class default method raise the TypeError
+            return super().default(obj)
+
+    @staticmethod
+    def geometry_hook(json_dict):
+        """Convert dictionaries back into geometry objects for decoding."""
+        if len(json_dict.items()) != 1:
+            raise ValueError(f"Invalid geometry json object {json_dict}")
+        for key, value in json_dict.items():
+            return CLASS_REGISTRY[key](*value)
+
+
 class Location:
     """Location in 3D space. Depending on usage can be absolute or relative.
 
@@ -1714,6 +1776,7 @@ class LocationEncoder(json.JSONEncoder):
 
     def default(self, o: Location) -> dict:
         """Return a serializable object"""
+        warnings.warn("Use GeomEncoder instead", DeprecationWarning, stacklevel=2)
         if not isinstance(o, Location):
             raise TypeError("Only applies to Location objects")
         return {"Location": o.to_tuple()}
@@ -1725,6 +1788,7 @@ def location_hook(obj) -> dict:
         Example:
             read_json = json.load(infile, object_hook=LocationEncoder.location_hook)
         """
+        warnings.warn("Use GeomEncoder instead", DeprecationWarning, stacklevel=2)
         if "Location" in obj:
             obj = Location(*[[float(f) for f in v] for v in obj["Location"]])
         return obj
@@ -2890,6 +2954,15 @@ def intersect(self, *args, **kwargs):
             return shape.intersect(self)
 
 
+CLASS_REGISTRY = {
+    "Axis": Axis,
+    "Color": Color,
+    "Location": Location,
+    "Plane": Plane,
+    "Vector": Vector,
+}
+
+
 def to_align_offset(
     min_point: VectorLike,
     max_point: VectorLike,

tests/test_direct_api/test_json.py

@@ -0,0 +1,92 @@
+"""
+build123d tests
+
+name: test_json.py
+by:   Gumyr
+date: February 24, 2025
+
+desc:
+    This python module contains tests for the build123d project.
+
+license:
+
+    Copyright 2025 Gumyr
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+"""
+
+import json
+import os
+import unittest
+from build123d.geometry import (
+    Axis,
+    Color,
+    GeomEncoder,
+    Location,
+    LocationEncoder,
+    Matrix,
+    Plane,
+    Rotation,
+    Vector,
+)
+
+
+class TestGeomEncode(unittest.TestCase):
+
+    def test_as_json(self):
+
+        a_json = json.dumps(Axis.Y, cls=GeomEncoder)
+        axis = json.loads(a_json, object_hook=GeomEncoder.geometry_hook)
+        self.assertEqual(Axis.Y, axis)
+
+        c_json = json.dumps(Color("red"), cls=GeomEncoder)
+        color = json.loads(c_json, object_hook=GeomEncoder.geometry_hook)
+        self.assertEqual(Color("red").to_tuple(), color.to_tuple())
+
+        loc = Location((0, 1, 2), (4, 8, 16))
+        l_json = json.dumps(loc, cls=GeomEncoder)
+        loc_json = json.loads(l_json, object_hook=GeomEncoder.geometry_hook)
+        self.assertAlmostEqual(loc.position, loc_json.position, 5)
+        self.assertAlmostEqual(loc.orientation, loc_json.orientation, 5)
+
+        with self.assertWarnsRegex(DeprecationWarning, "Use GeomEncoder instead"):
+            loc_legacy = json.loads(l_json, object_hook=LocationEncoder.location_hook)
+        self.assertAlmostEqual(loc.position, loc_legacy.position, 5)
+        self.assertAlmostEqual(loc.orientation, loc_legacy.orientation, 5)
+
+        p_json = json.dumps(Plane.XZ, cls=GeomEncoder)
+        plane = json.loads(p_json, object_hook=GeomEncoder.geometry_hook)
+        self.assertEqual(Plane.XZ, plane)
+
+        rot = Rotation((0, 1, 4))
+        r_json = json.dumps(rot, cls=GeomEncoder)
+        rotation = json.loads(r_json, object_hook=GeomEncoder.geometry_hook)
+        self.assertAlmostEqual(rot.position, rotation.position, 5)
+        self.assertAlmostEqual(rot.orientation, rotation.orientation, 5)
+
+        v_json = json.dumps(Vector(1, 2, 4), cls=GeomEncoder)
+        vector = json.loads(v_json, object_hook=GeomEncoder.geometry_hook)
+        self.assertEqual(Vector(1, 2, 4), vector)
+
+    def test_as_json_error(self):
+        with self.assertRaises(TypeError):
+            json.dumps(Matrix(), cls=GeomEncoder)
+
+        v_json = '{"Vector": [1.0, 2.0, 4.0], "Color": [0, 0, 0, 0]}'
+        with self.assertRaises(ValueError):
+            json.loads(v_json, object_hook=GeomEncoder.geometry_hook)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_direct_api/test_location.py

@@ -290,15 +290,17 @@ def test_as_json(self):
         }
 
         # Serializing json with custom Location encoder
-        json_object = json.dumps(data_dict, indent=4, cls=LocationEncoder)
+        with self.assertWarnsRegex(DeprecationWarning, "Use GeomEncoder instead"):
+            json_object = json.dumps(data_dict, indent=4, cls=LocationEncoder)
 
         # Writing to sample.json
         with open("sample.json", "w") as outfile:
             outfile.write(json_object)
 
         # Reading from sample.json
         with open("sample.json") as infile:
-            read_json = json.load(infile, object_hook=LocationEncoder.location_hook)
+            with self.assertWarnsRegex(DeprecationWarning, "Use GeomEncoder instead"):
+                read_json = json.load(infile, object_hook=LocationEncoder.location_hook)
 
         # Validate locations
         for key, value in read_json.items():