GearMaster CAD Module

User Manual — last updated 2026-03-30

The CAD module lets you load 3D geometry files, inspect the assembly structure, toggle visibility of individual components, and save the model state for future use — all without leaving GearMaster.

Two main classes do the work:

Quick Start

from GM_modules.Cad import GM_CadModel, CadEditor

model = GM_CadModel()
model.load("my_part.stp")      # load a STEP file

editor = CadEditor(model)
editor.show()                  # open the 3D viewer

To save the model state and reload it later:

model.save("my_part.gmcad")    # save as GearMaster native format

# next session:
model2 = GM_CadModel()
model2.load("my_part.gmcad")  # fast reload
editor2 = CadEditor(model2)
editor2.show()

STEP files .stp / .step

STEP is the standard 3D exchange format exported by CAD systems like SolidWorks, CATIA, Fusion 360, and FreeCAD. GearMaster reads AP203, AP214, and AP242 variants.

What gets imported

Length unit detection

GearMaster reads the unit declaration from the STEP header automatically (millimetres, inches, etc.). The detected unit is shown on the scale bar in the viewer (View → Toggle Scale Bar).

GearMaster native format .gmcad

The .gmcad format is GearMaster's own save format. It stores the complete model — geometry and state — so you can pick up exactly where you left off.

What is stored inside

A .gmcad file is a ZIP archive containing:

Recommended workflow

1. Export the STEP file from your CAD software.
2. Load it once with model.load("my_part.stp").
3. Open the viewer, adjust visibility and suppression as needed.
4. Save: model.save("my_part.gmcad").
5. From now on, load my_part.gmcad directly for faster reload and preserved state.

Interface layout

┌───────────────────────────────────────────────────────────────┐
│  File   View   Help                      ← menu bar           │
├───────────────┬───────────────────────────────────────────────┤
│               │                                               │
│  Feature Tree │         3D Viewport                           │
│               │                                               │
│  ▶ Assembly   │   (rotate · pan · zoom)                       │
│    ☑ Solid_1  │                                               │
│    ☑ Solid_2  │                                               │
│    ☑ Solid_3  │                                               │
│               │                                               │
└───────────────┴───────────────────────────────────────────────┘
│  [ View Mode ]   ← mode toolbar
└───────────────────────────────────────────────────────────────┘

The window is divided into three areas:

Mouse & keyboard controls

Mouse

Keyboard

File menu

View menu

Feature Tree

The Feature Tree on the left lists every component of the assembly in a hierarchical structure matching the STEP file structure.

Selecting an entity

Click on a name in the tree to highlight the corresponding geometry in orange in the viewport. You can also click directly on a solid in the 3D viewport to select it — the tree scrolls to the matching entry automatically.

Showing / hiding (Edit mode only)

In Edit mode, each leaf entity has a checkbox. Unchecking it hides the entity in the viewport. The entity is still included in geometric calculations (volume, bounding box).

Context menu (right-click, Edit mode only)

View mode vs Edit mode

The mode toolbar button at the bottom of the window toggles between the two operating modes:

What is an entity?

An entity is a single node in the assembly tree. It can be:

Each entity has two independent flags:

Suppress vs Hide: what is the difference?

Sub-entity selection — overview

The CAD viewport supports contextual sub-entity selection: a single left-click in the 3D scene resolves automatically to the finest geometric element under the cursor — a vertex, an edge, or a face. The selected element is highlighted in orange as a visual overlay on top of the entity mesh.

The selection is held in memory inside the editor and is accessible via the editor.selection property, which gives you programmatic access to the underlying OCC geometry objects (TopoDS_Face, TopoDS_Edge, TopoDS_Vertex). This is the foundation for future operations such as applying loads and boundary conditions.

How to select faces, edges, and vertices

Contextual picking logic

Every left-click in the viewport performs a contextual pick: the system queries the distance from the click position to each nearby vertex and edge in screen space and selects the closest element above a threshold.

Single and multi-select

Visual feedback

• Face selected: a translucent orange overlay patch is drawn on top of the face triangles.
• Edge selected: an orange thick line (width 4) is drawn along the edge curve.
• Vertex selected: an orange sphere (sized at 1 % of the model bounding-box diagonal) is placed at the vertex coordinates.

Sub-entity selection — Python API

After the user clicks in the viewport, the selection state is available through the editor.selection property:

editor = CadEditor(model)
editor.show(blocking=False)
# … user clicks in the viewport …

state = editor.selection         # SelectionState object
print(state)                     # SelectionState(faces=1, edges=0, vertices=0)

# Access selected faces
for face in state.faces:
    print(face.entity_id)        # e.g. "e003"
    print(face.face_index)       # 0-based index
    occ_face = face.occ_face     # TopoDS_Face — usable with pythonOCC

# Access selected edges
for edge in state.edges:
    occ_edge = edge.occ_edge     # TopoDS_Edge

# Access selected vertices
for vtx in state.vertices:
    print(vtx.position)          # numpy array [x, y, z]
    occ_vtx = vtx.occ_vertex     # TopoDS_Vertex

# Programmatic clear
editor.clear_selection()

SelectionState — add / remove programmatically

You can also manipulate the selection state directly from Python without user interaction. Call the add/remove methods and then editor._window._refresh_selection_overlay() to redraw.

Python API quick reference