Skip to content

Builder

The main entry point for generating magnetic component geometry.

OpenMagneticsVirtualBuilder.builder.Builder

Facade that delegates to a CadQuery or FreeCAD rendering engine.

The Builder class is the main entry point for generating magnetic component geometry. It selects and wraps one of two CAD engines and exposes a uniform API for core generation, assembly, bobbin/winding creation, and technical drawing export.

Parameters:

Name Type Description Default
engine

Engine name, either "CadQuery" (default) or "FreeCAD".

 'CadQuery'
Example

builder = Builder("CadQuery") families = builder.get_families()

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
class Builder:
    """Facade that delegates to a CadQuery or FreeCAD rendering engine.

    The Builder class is the main entry point for generating magnetic component
    geometry. It selects and wraps one of two CAD engines and exposes a
    uniform API for core generation, assembly, bobbin/winding creation,
    and technical drawing export.

    Args:
        engine: Engine name, either ``"CadQuery"`` (default) or ``"FreeCAD"``.

    Example:
        >>> builder = Builder("CadQuery")
        >>> families = builder.get_families()
    """

    def __init__(self, engine="CadQuery"):
        if engine == "FreeCAD":
            import freecad_builder

            self.engine = freecad_builder.FreeCADBuilder()
        else:
            import cadquery_builder

            self.engine = cadquery_builder.CadQueryBuilder()

    def factory(self, data):
        """Create a shape-specific builder from MAS JSON data.

        Args:
            data: Dictionary with at least a ``"family"`` key matching a
                :class:`~OpenMagneticsVirtualBuilder.utils.ShapeFamily` member.

        Returns:
            A shape builder instance (e.g. ``E``, ``Pq``, ``T``) for the
            requested family.
        """
        return self.engine.factory(data)

    def get_families(self):
        """List all available core shape families with their dimensions.

        Returns:
            Dict mapping family name (lowercase) to a dict of subtype numbers
            and their dimension letters.
        """
        return {shaper.name.lower().replace("_", " "): self.factory({"family": shaper.name}).get_dimensions_and_subtypes() for shaper in self.engine.shapers}

    def get_spacer(self, geometrical_data):
        """Generate spacer geometry for gapped cores.

        Args:
            geometrical_data: MAS geometrical description list.

        Returns:
            CadQuery/FreeCAD geometry for the spacer.
        """
        return self.engine.get_spacer(geometrical_data)

    def get_core(self, project_name, geometrical_description, output_path=None, save_files=True, export_files=True):
        """Generate full 3D core geometry from a MAS geometrical description.

        Handles multi-piece cores (top/bottom halves) and applies gapping
        (machining) when specified.

        Args:
            project_name: Base name for output files.
            geometrical_description: List of MAS piece descriptions, each
                containing shape data, dimensions, and optional machining.
            output_path: Directory for output files. Defaults to ``output/``.
            save_files: Whether to save FreeCAD project files.
            export_files: Whether to export STEP/STL files.

        Returns:
            Tuple ``(step_path, stl_path)`` when ``export_files`` is True,
            or a list of CadQuery/FreeCAD pieces otherwise.
        """
        if output_path is None:
            output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
        return self.engine.get_core(project_name, geometrical_description, output_path, save_files, export_files)

    def get_core_gapping_technical_drawing(self, project_name, core_data, colors=None, output_path=None, save_files=True, export_files=True):
        """Generate a technical drawing showing core gapping details.

        Produces an SVG drawing with dimension annotations for the core
        cross-section, highlighting gap positions and lengths.

        Args:
            project_name: Base name for output files.
            core_data: MAS core data dictionary with ``geometricalDescription``
                and ``processedDescription`` (including ``gapping``).
            colors: Optional dict with ``"projection_color"`` and
                ``"dimension_color"`` hex values.
            output_path: Directory for output files.
            save_files: Whether to save intermediate files.
            export_files: Whether to export final SVG.

        Returns:
            SVG string of the technical drawing.
        """
        if output_path is None:
            output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
        return self.engine.get_core_gapping_technical_drawing(project_name, core_data, colors, output_path, save_files, export_files)

    def get_magnetic_assembly(self, project_name, assembly_data, output_path=None, save_files=True, export_files=True):
        """Generate a full magnetic assembly (core + bobbin + coil).

        Args:
            project_name: Base name for output files.
            assembly_data: MAS assembly data containing core, coil, and
                bobbin descriptions.
            output_path: Directory for output files.
            save_files: Whether to save intermediate files.
            export_files: Whether to export STEP/STL.

        Returns:
            Tuple ``(step_path, stl_path)`` when ``export_files`` is True.
        """
        if output_path is None:
            output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
        return self.engine.get_magnetic_assembly(project_name, assembly_data, output_path, save_files, export_files)

    def get_bobbin(self, bobbin_data, winding_window, name="Bobbin", output_path=None, save_files=False, export_files=True):
        """Generate a bobbin (coil former) geometry.

        Args:
            bobbin_data: MAS bobbin description with ``processedDescription``.
            winding_window: Dict with ``height`` and ``width`` keys (meters).
            name: Part name for the output files.
            output_path: Directory for output files.
            save_files: Whether to save intermediate files.
            export_files: Whether to export STEP/STL.

        Returns:
            Tuple ``(step_path, stl_path)`` when ``export_files`` is True.
        """
        if output_path is None:
            output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
        return self.engine.get_bobbin(bobbin_data, winding_window, name, output_path, save_files, export_files)

    def get_winding(self, winding_data, bobbin_dims, name="Winding", output_path=None, save_files=False, export_files=True):
        """Generate winding (coil) geometry.

        Args:
            winding_data: MAS winding description with wire type, turns, etc.
            bobbin_dims: Dict with ``width`` and ``height`` keys.
            name: Part name for output files.
            output_path: Directory for output files.
            save_files: Whether to save intermediate files.
            export_files: Whether to export STEP/STL.

        Returns:
            Tuple ``(step_path, stl_path)`` when ``export_files`` is True.
        """
        if output_path is None:
            output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
        return self.engine.get_winding(winding_data, bobbin_dims, name, output_path, save_files, export_files)

    def get_magnetic(self, magnetic_data, project_name="Magnetic", output_path=None, export_files=True):
        """Create a complete 3D magnetic component from MAS data.

        Parameters
        ----------
        magnetic_data : dict
            MAS magnetic description dictionary containing core, coil, etc.
            Can be either a complete MAS file (with 'magnetic' key) or just the magnetic data.
        project_name : str
            Name for the output files.
        output_path : str
            Path to save output files.
        export_files : bool
            If True, export STEP and STL files.

        Returns
        -------
        Tuple of (step_path, stl_path) or list of pieces if export_files is False.
        """
        if output_path is None:
            output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
        # Handle both full MAS format and just magnetic data
        if "magnetic" in magnetic_data:
            magnetic_data = magnetic_data["magnetic"]
        return self.engine.get_magnetic(magnetic_data, project_name, output_path, export_files)

    def get_svg_drawings(self, project_name, geometrical_description, **kwargs):
        """Generate annotated SVG drawings for a core shape."""
        return self.engine.get_svg_drawings(project_name, geometrical_description, **kwargs)

    def get_dxf_drawings(self, project_name, geometrical_description, **kwargs):
        """Generate DXF drawings for a core shape."""
        return self.engine.get_dxf_drawings(project_name, geometrical_description, **kwargs)

    def get_fcstd_sketches(self, project_name, geometrical_description, **kwargs):
        """Generate FreeCAD macro files for a core shape."""
        return self.engine.get_fcstd_sketches(project_name, geometrical_description, **kwargs)

    def get_assembly_svg_drawings(self, project_name, magnetic_data, **kwargs):
        """Generate annotated SVG drawings for assembly or individual components."""
        return self.engine.get_assembly_svg_drawings(project_name, magnetic_data, **kwargs)

    def get_assembly_dxf_drawings(self, project_name, magnetic_data, **kwargs):
        """Generate DXF drawings for assembly or individual components."""
        return self.engine.get_assembly_dxf_drawings(project_name, magnetic_data, **kwargs)

    def get_assembly_fcstd_sketches(self, project_name, magnetic_data, **kwargs):
        """Generate FreeCAD macro files for assembly or individual components."""
        return self.engine.get_assembly_fcstd_sketches(project_name, magnetic_data, **kwargs)

factory 

factory(data)

Create a shape-specific builder from MAS JSON data.

Parameters:

Name Type Description Default
data

Dictionary with at least a "family" key matching a :class:~OpenMagneticsVirtualBuilder.utils.ShapeFamily member.

 required

Returns:

Type Description

A shape builder instance (e.g. E, Pq, T) for the

requested family.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
44
45
46
47
48
49
50
51
52
53
54
55
def factory(self, data):
    """Create a shape-specific builder from MAS JSON data.

    Args:
        data: Dictionary with at least a ``"family"`` key matching a
            :class:`~OpenMagneticsVirtualBuilder.utils.ShapeFamily` member.

    Returns:
        A shape builder instance (e.g. ``E``, ``Pq``, ``T``) for the
        requested family.
    """
    return self.engine.factory(data)

get_families 

get_families()

List all available core shape families with their dimensions.

Returns:

Type Description

Dict mapping family name (lowercase) to a dict of subtype numbers

and their dimension letters.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
57
58
59
60
61
62
63
64
def get_families(self):
    """List all available core shape families with their dimensions.

    Returns:
        Dict mapping family name (lowercase) to a dict of subtype numbers
        and their dimension letters.
    """
    return {shaper.name.lower().replace("_", " "): self.factory({"family": shaper.name}).get_dimensions_and_subtypes() for shaper in self.engine.shapers}

get_spacer 

get_spacer(geometrical_data)

Generate spacer geometry for gapped cores.

Parameters:

Name Type Description Default
geometrical_data

MAS geometrical description list.

 required

Returns:

Type Description

CadQuery/FreeCAD geometry for the spacer.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
66
67
68
69
70
71
72
73
74
75
def get_spacer(self, geometrical_data):
    """Generate spacer geometry for gapped cores.

    Args:
        geometrical_data: MAS geometrical description list.

    Returns:
        CadQuery/FreeCAD geometry for the spacer.
    """
    return self.engine.get_spacer(geometrical_data)

get_core 

get_core(project_name, geometrical_description, output_path=None, save_files=True, export_files=True)

Generate full 3D core geometry from a MAS geometrical description.

Handles multi-piece cores (top/bottom halves) and applies gapping (machining) when specified.

Parameters:

Name Type Description Default
project_name

Base name for output files.

 required
geometrical_description

List of MAS piece descriptions, each containing shape data, dimensions, and optional machining.

 required
output_path

Directory for output files. Defaults to output/.

 None
save_files

Whether to save FreeCAD project files.

 True
export_files

Whether to export STEP/STL files.

 True

Returns:

Type Description

Tuple (step_path, stl_path) when export_files is True,

or a list of CadQuery/FreeCAD pieces otherwise.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def get_core(self, project_name, geometrical_description, output_path=None, save_files=True, export_files=True):
    """Generate full 3D core geometry from a MAS geometrical description.

    Handles multi-piece cores (top/bottom halves) and applies gapping
    (machining) when specified.

    Args:
        project_name: Base name for output files.
        geometrical_description: List of MAS piece descriptions, each
            containing shape data, dimensions, and optional machining.
        output_path: Directory for output files. Defaults to ``output/``.
        save_files: Whether to save FreeCAD project files.
        export_files: Whether to export STEP/STL files.

    Returns:
        Tuple ``(step_path, stl_path)`` when ``export_files`` is True,
        or a list of CadQuery/FreeCAD pieces otherwise.
    """
    if output_path is None:
        output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
    return self.engine.get_core(project_name, geometrical_description, output_path, save_files, export_files)

get_core_gapping_technical_drawing 

get_core_gapping_technical_drawing(project_name, core_data, colors=None, output_path=None, save_files=True, export_files=True)

Generate a technical drawing showing core gapping details.

Produces an SVG drawing with dimension annotations for the core cross-section, highlighting gap positions and lengths.

Parameters:

Name Type Description Default
project_name

Base name for output files.

 required
core_data

MAS core data dictionary with geometricalDescription and processedDescription (including gapping).

 required
colors

Optional dict with "projection_color" and "dimension_color" hex values.

 None
output_path

Directory for output files.

 None
save_files

Whether to save intermediate files.

 True
export_files

Whether to export final SVG.

 True

Returns:

Type Description

SVG string of the technical drawing.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def get_core_gapping_technical_drawing(self, project_name, core_data, colors=None, output_path=None, save_files=True, export_files=True):
    """Generate a technical drawing showing core gapping details.

    Produces an SVG drawing with dimension annotations for the core
    cross-section, highlighting gap positions and lengths.

    Args:
        project_name: Base name for output files.
        core_data: MAS core data dictionary with ``geometricalDescription``
            and ``processedDescription`` (including ``gapping``).
        colors: Optional dict with ``"projection_color"`` and
            ``"dimension_color"`` hex values.
        output_path: Directory for output files.
        save_files: Whether to save intermediate files.
        export_files: Whether to export final SVG.

    Returns:
        SVG string of the technical drawing.
    """
    if output_path is None:
        output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
    return self.engine.get_core_gapping_technical_drawing(project_name, core_data, colors, output_path, save_files, export_files)

get_magnetic_assembly 

get_magnetic_assembly(project_name, assembly_data, output_path=None, save_files=True, export_files=True)

Generate a full magnetic assembly (core + bobbin + coil).

Parameters:

Name Type Description Default
project_name

Base name for output files.

 required
assembly_data

MAS assembly data containing core, coil, and bobbin descriptions.

 required
output_path

Directory for output files.

 None
save_files

Whether to save intermediate files.

 True
export_files

Whether to export STEP/STL.

 True

Returns:

Type Description

Tuple (step_path, stl_path) when export_files is True.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def get_magnetic_assembly(self, project_name, assembly_data, output_path=None, save_files=True, export_files=True):
    """Generate a full magnetic assembly (core + bobbin + coil).

    Args:
        project_name: Base name for output files.
        assembly_data: MAS assembly data containing core, coil, and
            bobbin descriptions.
        output_path: Directory for output files.
        save_files: Whether to save intermediate files.
        export_files: Whether to export STEP/STL.

    Returns:
        Tuple ``(step_path, stl_path)`` when ``export_files`` is True.
    """
    if output_path is None:
        output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
    return self.engine.get_magnetic_assembly(project_name, assembly_data, output_path, save_files, export_files)

get_bobbin 

get_bobbin(bobbin_data, winding_window, name='Bobbin', output_path=None, save_files=False, export_files=True)

Generate a bobbin (coil former) geometry.

Parameters:

Name Type Description Default
bobbin_data

MAS bobbin description with processedDescription.

 required
winding_window

Dict with height and width keys (meters).

 required
name

Part name for the output files.

 'Bobbin'
output_path

Directory for output files.

 None
save_files

Whether to save intermediate files.

 False
export_files

Whether to export STEP/STL.

 True

Returns:

Type Description

Tuple (step_path, stl_path) when export_files is True.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def get_bobbin(self, bobbin_data, winding_window, name="Bobbin", output_path=None, save_files=False, export_files=True):
    """Generate a bobbin (coil former) geometry.

    Args:
        bobbin_data: MAS bobbin description with ``processedDescription``.
        winding_window: Dict with ``height`` and ``width`` keys (meters).
        name: Part name for the output files.
        output_path: Directory for output files.
        save_files: Whether to save intermediate files.
        export_files: Whether to export STEP/STL.

    Returns:
        Tuple ``(step_path, stl_path)`` when ``export_files`` is True.
    """
    if output_path is None:
        output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
    return self.engine.get_bobbin(bobbin_data, winding_window, name, output_path, save_files, export_files)

get_winding 

get_winding(winding_data, bobbin_dims, name='Winding', output_path=None, save_files=False, export_files=True)

Generate winding (coil) geometry.

Parameters:

Name Type Description Default
winding_data

MAS winding description with wire type, turns, etc.

 required
bobbin_dims

Dict with width and height keys.

 required
name

Part name for output files.

 'Winding'
output_path

Directory for output files.

 None
save_files

Whether to save intermediate files.

 False
export_files

Whether to export STEP/STL.

 True

Returns:

Type Description

Tuple (step_path, stl_path) when export_files is True.
Source code in src/OpenMagneticsVirtualBuilder/builder.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def get_winding(self, winding_data, bobbin_dims, name="Winding", output_path=None, save_files=False, export_files=True):
    """Generate winding (coil) geometry.

    Args:
        winding_data: MAS winding description with wire type, turns, etc.
        bobbin_dims: Dict with ``width`` and ``height`` keys.
        name: Part name for output files.
        output_path: Directory for output files.
        save_files: Whether to save intermediate files.
        export_files: Whether to export STEP/STL.

    Returns:
        Tuple ``(step_path, stl_path)`` when ``export_files`` is True.
    """
    if output_path is None:
        output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
    return self.engine.get_winding(winding_data, bobbin_dims, name, output_path, save_files, export_files)

get_magnetic 

get_magnetic(magnetic_data, project_name='Magnetic', output_path=None, export_files=True)

Create a complete 3D magnetic component from MAS data.

Parameters

magnetic_data : dict MAS magnetic description dictionary containing core, coil, etc. Can be either a complete MAS file (with 'magnetic' key) or just the magnetic data. project_name : str Name for the output files. output_path : str Path to save output files. export_files : bool If True, export STEP and STL files.

Returns

Tuple of (step_path, stl_path) or list of pieces if export_files is False.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
def get_magnetic(self, magnetic_data, project_name="Magnetic", output_path=None, export_files=True):
    """Create a complete 3D magnetic component from MAS data.

    Parameters
    ----------
    magnetic_data : dict
        MAS magnetic description dictionary containing core, coil, etc.
        Can be either a complete MAS file (with 'magnetic' key) or just the magnetic data.
    project_name : str
        Name for the output files.
    output_path : str
        Path to save output files.
    export_files : bool
        If True, export STEP and STL files.

    Returns
    -------
    Tuple of (step_path, stl_path) or list of pieces if export_files is False.
    """
    if output_path is None:
        output_path = f"{os.path.dirname(os.path.abspath(__file__))}/../../output/"
    # Handle both full MAS format and just magnetic data
    if "magnetic" in magnetic_data:
        magnetic_data = magnetic_data["magnetic"]
    return self.engine.get_magnetic(magnetic_data, project_name, output_path, export_files)

get_svg_drawings 

get_svg_drawings(project_name, geometrical_description, **kwargs)

Generate annotated SVG drawings for a core shape.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
202
203
204
def get_svg_drawings(self, project_name, geometrical_description, **kwargs):
    """Generate annotated SVG drawings for a core shape."""
    return self.engine.get_svg_drawings(project_name, geometrical_description, **kwargs)

get_dxf_drawings 

get_dxf_drawings(project_name, geometrical_description, **kwargs)

Generate DXF drawings for a core shape.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
206
207
208
def get_dxf_drawings(self, project_name, geometrical_description, **kwargs):
    """Generate DXF drawings for a core shape."""
    return self.engine.get_dxf_drawings(project_name, geometrical_description, **kwargs)

get_fcstd_sketches 

get_fcstd_sketches(project_name, geometrical_description, **kwargs)

Generate FreeCAD macro files for a core shape.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
210
211
212
def get_fcstd_sketches(self, project_name, geometrical_description, **kwargs):
    """Generate FreeCAD macro files for a core shape."""
    return self.engine.get_fcstd_sketches(project_name, geometrical_description, **kwargs)

get_assembly_svg_drawings 

get_assembly_svg_drawings(project_name, magnetic_data, **kwargs)

Generate annotated SVG drawings for assembly or individual components.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
214
215
216
def get_assembly_svg_drawings(self, project_name, magnetic_data, **kwargs):
    """Generate annotated SVG drawings for assembly or individual components."""
    return self.engine.get_assembly_svg_drawings(project_name, magnetic_data, **kwargs)

get_assembly_dxf_drawings 

get_assembly_dxf_drawings(project_name, magnetic_data, **kwargs)

Generate DXF drawings for assembly or individual components.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
218
219
220
def get_assembly_dxf_drawings(self, project_name, magnetic_data, **kwargs):
    """Generate DXF drawings for assembly or individual components."""
    return self.engine.get_assembly_dxf_drawings(project_name, magnetic_data, **kwargs)

get_assembly_fcstd_sketches 

get_assembly_fcstd_sketches(project_name, magnetic_data, **kwargs)

Generate FreeCAD macro files for assembly or individual components.

Source code in src/OpenMagneticsVirtualBuilder/builder.py 
222
223
224
def get_assembly_fcstd_sketches(self, project_name, magnetic_data, **kwargs):
    """Generate FreeCAD macro files for assembly or individual components."""
    return self.engine.get_assembly_fcstd_sketches(project_name, magnetic_data, **kwargs)