gtrace.draw.serialize

Serialization of gtrace drawing canvases and beams into JSON-compatible dictionaries.

This module provides an alternative “renderer” that, instead of writing a DXF file, converts a Canvas (and optionally a list of GaussianBeams) into plain Python dictionaries composed only of JSON-serializable types (dict, list, str, float, int, bool, None). The output is consumed by the HTML/JS viewer and other GUI front ends.

All coordinates are kept in the unit of the canvas (usually meters). Complex numbers are represented as [real, imag] pairs.

Attributes

`__author__`
`__copyright__`
`__credits__`
`__license__`
`__version__`
`__maintainer__`
`__email__`
`__status__`
`NEW_SHAPES`
`_OPTIC_SCALARS`
`_OPTIC_POINTS`
`_OPTIC_ANGLES`
`_OPTIC_FLAGS`
`_OPTIC_INTS`

Exceptions

UnknownShapeError

Raised when a shape cannot be serialized or rebuilt.

Functions

`_vec`(v)	Convert a 2D vector (numpy array, list or tuple) to [float, float].
`_floats`(v)	Convert a sequence of numbers to a list of floats.
`_complex`(c)	Convert a complex number to a [real, imag] pair.
`new_shapes`()	A copy of NEW_SHAPES, kind by kind.
`shape_to_dict`(s)	Convert a single draw.Shape into a JSON-compatible dict.
`shape_from_dict`(d)	Rebuild a draw.Shape from a dict produced by shape_to_dict().
`build_shape`(d[, error])	Build a shape from a dict and refuse one that cannot be drawn.
`canvas_to_dict`(canvas)	Convert a draw.Canvas into a JSON-compatible dict.
`beam_to_dict`(b)	Convert a GaussianBeam into a JSON-compatible dict of its
`beams_to_dict`(beamList)	Convert a list of GaussianBeams into a list of JSON-compatible
`optic_to_dict`(o)	Convert an Optics into a JSON-compatible dict of the attributes a
`optics_to_dict`(opticsList)	Convert a list of Optics into a list of JSON-compatible dicts.
`scene_to_dict`(canvas[, beamList, opticsList, display])	Convert a canvas, an optional list of beams and an optional list of

Module Contents

gtrace.draw.serialize.__author__ = 'Yoichi Aso'

gtrace.draw.serialize.__copyright__ = 'Copyright 2011-2026, Yoichi Aso'

gtrace.draw.serialize.__credits__ = ['Yoichi Aso']

gtrace.draw.serialize.__license__ = 'BSD'

gtrace.draw.serialize.__version__ = '0.8.0'

gtrace.draw.serialize.__maintainer__ = 'Yoichi Aso'

gtrace.draw.serialize.__email__ = 'asoy01@gmail.com'

gtrace.draw.serialize.__status__ = 'Beta'

exception gtrace.draw.serialize.UnknownShapeError(message)

Bases: Exception

Raised when a shape cannot be serialized or rebuilt.

Derived from Exception, not BaseException: the copy of this class in renderer.py was fixed the same way on 2026-08-04, after a BaseException sailed through every ‘except Exception’ between the renderer and the user - including the one that would have shown the failure in the GUI.

message

gtrace.draw.serialize._vec(v): Convert a 2D vector (numpy array, list or tuple) to [float, float].

gtrace.draw.serialize._floats(v): Convert a sequence of numbers to a list of floats.

gtrace.draw.serialize._complex(c): Convert a complex number to a [real, imag] pair.

gtrace.draw.serialize.NEW_SHAPES

gtrace.draw.serialize.new_shapes()

A copy of NEW_SHAPES, kind by kind.

A copy, because what comes back is handed to a front end and to whoever asks: a caller that scaled the dict it was given would otherwise resize every shape put down after it.

Return type:: dict

gtrace.draw.serialize.shape_to_dict(s)

Convert a single draw.Shape into a JSON-compatible dict.

The type of the shape is stored in the ‘type’ key.

gtrace.draw.serialize.shape_from_dict(d)

Rebuild a draw.Shape from a dict produced by shape_to_dict().

The inverse exists because a Mechanics carries its geometry as shapes: a saved layout writes them out with shape_to_dict, and loading it - or receiving them in an edit message - has to build the primitives back.

Raises:: UnknownShapeError – If the dict does not describe a shape gtrace can draw. A malformed dict (a missing key, a value of the wrong kind) comes back as whatever the constructor raised.

gtrace.draw.serialize.build_shape(d, error=None)

Build a shape from a dict and refuse one that cannot be drawn.

shape_from_dict() is the constructor’s door: what describes no shape is refused by the constructor itself, so there is no second list of rules about what a circle is. What it cannot catch is a shape that builds and then cannot be drawn - a rectangle of no width, a coordinate at infinity - because those are numbers a constructor has no opinion about. They are caught here.

Both places a shape is edited come through this: the shape editor drawing a part, and a layout editing the one shape of a body drawn on the bench. A rule kept in one of them would be a rule the other did not have.

Parameters:

d (dict) – A shape as shape_to_dict() writes it.
error (type or None, optional) – What to raise instead of ValueError, for a caller whose protocol has an exception of its own.

Return type:

A drawing primitive.

Raises:

ValueError, or whatever error names – If the dict describes no shape, or one that cannot be drawn.

gtrace.draw.serialize.canvas_to_dict(canvas)

Convert a draw.Canvas into a JSON-compatible dict.

The structure of the returned dict is:

{'unit': 'm',
 'layers': [{'name': str,
             'color': [r, g, b],
             'shapes': [shape dict, ...]},
            ...]}

Coordinates are kept in the unit of the canvas (no scaling is applied, unlike renderDXF which converts to mm).

gtrace.draw.serialize.beam_to_dict(b)

Convert a GaussianBeam into a JSON-compatible dict of its physical parameters.

This is the metadata channel that DXF export does not have. It allows a viewer to compute the beam parameters (q, width, ROC, Gouy phase, etc.) at an arbitrary point along the beam.

The q-parameters are given at the origin of the beam (‘pos’). The parameters at a distance d along the beam are obtained by q -> q + d.

gtrace.draw.serialize.beams_to_dict(beamList): Convert a list of GaussianBeams into a list of JSON-compatible dicts. See beam_to_dict for the format of each element.

gtrace.draw.serialize._OPTIC_SCALARS = ['diameter', 'thickness', 'wedgeAngle', 'inv_ROC_HR', 'inv_ROC_AR', 'n', 'Refl_HR', 'Trans_HR',...

gtrace.draw.serialize._OPTIC_POINTS = ['HRcenter', 'ARcenter', 'center']

gtrace.draw.serialize._OPTIC_ANGLES = ['normAngleHR', 'normAngleAR']

gtrace.draw.serialize._OPTIC_FLAGS = ['HRtransmissive', 'HRreflective', 'term_on_HR', 'term_on_HR_transmits']

gtrace.draw.serialize._OPTIC_INTS = ['term_on_HR_order']

gtrace.draw.serialize.optic_to_dict(o)

Convert an Optics into a JSON-compatible dict of the attributes a viewer needs in order to point at it: where it is, how big it is and which way it faces.

Unlike the shapes on the canvas, this keeps the identity of the optics, which is what lets a GUI say “the user grabbed M1”. Attributes that a particular class does not have are left out.

gtrace.draw.serialize.optics_to_dict(opticsList): Convert a list of Optics into a list of JSON-compatible dicts. See optic_to_dict for the format of each element.

gtrace.draw.serialize.scene_to_dict(canvas, beamList=None, opticsList=None, display=None)

Convert a canvas, an optional list of beams and an optional list of optics into a single JSON-compatible dict:

{‘canvas’: canvas dict,: ‘beams’: [beam dict, …], ‘optics’: [optic dict, …], ‘display’: {…}}

This is the top-level data structure consumed by the HTML/JS viewer. The ‘optics’ entry is what an editing front end addresses when the user drags an element. ‘display’ tells the front end how the canvas was drawn - the envelope width and which transverse direction it shows - so that its controls can show the choice in force rather than guessing.

OpticalLayout.scene_dict adds channels of its own on top of these - the dimensions noted on the layout, the points a measurement may snap to, and whether undo and redo have anything to work with. They are added there rather than here because they belong to the layout rather than to a drawing: a canvas and a list of beams, which is all this function is given, know nothing of them.