GD&T

[max-mrgrsk]

This is the first pass to kick off an mvp. It is a compact guide to what “annotations” actually are, why engineers use them, and how they’re organized. In order to define the minimal, standards‑aligned set to encode in KCL now, with a clear path to 3D projection and drawings later.

Importance of CAD Annotations

CAD annotations – such as dimensions, tolerances, and notes – are essential to fully communicate a 3D design’s intent. A 3D model alone only shows ideal geometry; annotations convey how that geometry may vary in the real world and still function. Engineers in aerospace, automotive, and machinery rely on standardized annotation practices (notably Geometric Dimensioning & Tolerancing, GD&T) to control manufacturing variations and ensure parts meet their intended form, fit, and function

Reasoning:

• Communicating Allowable Variations: No manufactured part is exactly like the perfect CAD model – there are always small deviations. Annotations (like tolerances) explicitly state how much variation is acceptable.
• Ensuring Fit, Function, and Interchangeability: In complex assemblies (aircraft, cars, machinery), all components must fit and work together correctly. Engineers use tolerances and GD&T symbols to guarantee critical features will align and function even with small manufacturing imperfections
• Standardized Symbol Language (GD&T): Annotations follow international standards (e.g. ASME Y14.5) so that design requirements are unambiguous. GD&T symbols represent design intent rather than just numeric geometry
• Single Source of Truth (Model-Based Definition): Modern aerospace and automotive companies increasingly embed annotations directly in the 3D model (a practice called Model-Based Definition, MBD). A fully annotated 3D model can serve as the authoritative design document, often replacing traditional drawings

Annotations are needed in CAD to bridge the gap between the ideal model and real-world production. They communicate exactly how precise each feature must be, which features are critical, and how to inspect them. Without annotations, a 3D model is incomplete – it doesn’t tell an engineer or machinist the full story of how to build or check the part. This is why aerospace engineers consider annotations (dimensions, tolerances, GD&T callouts, notes) an integral part of the design.

Essential Annotation Features for the MVP

Core annotation types that provide the most value to engineers. Below is a list of the most essential annotations to include in the MVP.

1. Flatness Tolerance (Geometric Form Control) gdt::flatness(...)
2. Datum Feature Definitions: (Foundational for the above tolerances) gdt::datum(...)
3. Profile Tolerance (Surface/Profile of a Line) gdt::profile(...)
4. Position Tolerances (Locational Accuracy for Features) gdt::position(...)
5. Orientation Tolerances (Perpendicularity & Parallelism) gdt::perpendicularity(...), gdt::parallelism(...)
6. Dimensional Annotations with Tolerances gdt::dimension(...)
7. General Notes or Text Annotations (if applicable) gdt::note(...)

References:

edgeOf(), edgeOf()
Out of mvp scope: centerOf(), pointOf(), axisOf(), centerPlaneOf(), sectionCurveOf()

GDT parameters:

references: faces = [face1], edges = [edge01]
tolerance = 0.1mm
precision = 3_

Style parameters:

framePosition = [10, 10]
inPlane = XY
fontPointSize = 36_
fontScale = 1.0_

Out of scope:

name = string
note = string
positiveTolerance = number
negativeTolerance = number
id = string
tag = string
category = string
visibility = 'all' | 'code' | '3D' | 'drawing' = 'all'

Roadmap:

Profile, position, and flatness together address the majority of needs for CAD model annotations.

Since flatness can be implemented rn — start with it.

step 1 - gdt::flatness(faces = [face1], tolerance = 0.1mm, precision = 3_, ...) ✅ Done!

profile and position will require the datum - next step
datum in ~95% of cases is attached to the surface — mvp scope

step 2 - gdt::datum(face = face1, name=A, ... ) PR

datum unlocks all other tolerances.
mvp position tolerance should reference a face - can be done rn, similarly to flatness

step 3 gdt::position(faces = [face1], datums=[A], tolerance = 0.1mm, precision = 3_, ...)

mvp orientation tolerance is same as position, so we can go for it straight away:

step 4 gdt::perpendicularity(...)

step 5 gdt::parallelism(...)

mvp profile tolerance should reference an edge - needs edge reference implementation

step 6 - edge reference edge1 = edgeOf(faces = [face1, face2])

now we can implement profile tolerance:

step 7 - gdt::profile(edges = [edge1], datums=[A], tolerance = 0.1mm, precision = 3_, ...)

now we can implement dimensions
radius and diameter have to be referenced to edges - can be implemented rn

step 8 - gdt::radius(edges = [edge1], datums=[A], tolerance = 0.1mm, precision = 3_, ...)

step 9 - gdt::diameter(edges = [edge1], datums=[A], tolerance = 0.1mm, precision = 3_, ...)

linear dimensions need point (vertex) reference implementation

step 10 - point reference point1 = pointOf(faces = [face1, face2, face3]) or ...(edges = [edge1, edge2])

now we can implement dimensions:

step 11 - linear dimension gdt::dimension(points = [point1, point2], datums=[A], tolerance = 0.1mm, precision = 3_, ...)

last step - notes (can be referenced to anything)

step 12 - notes gdt::note(note = string)

the last missing bit is a center plane
it can be referenced adding datum to the dimension

step 13 - center plane gdt::datum(dimension = dimension01)

Example

// GDT example

@settings(
  defaultLengthUnit = mm,
  experimentalFeatures = allow
)

// Parameters
length = 20
width = 30
height = 10

// Sketch rectangle centered at origin
sketch = startSketchOn(XY)
profile = startProfile(sketch, at = [-length / 2, -width / 2])
  |> xLine(length = length)
  |> yLine(length = width, tag = $face02)
  |> xLine(length = -length)
  |> close()

// Extrude to create the box
box = extrude(profile, length = height, tagEnd = $face01)

// GDT


fontPointSize = 10
fontScale = 1

gdt::flatness(
  faces = [face01],
  tolerance = 0.1mm,
  precision = 3_,
  framePosition = [10, 10],
  framePlane = XZ,
  fontPointSize,
  fontScale,
)

// Not merged:

gdt::datum(
  face = face02,
  name = "A",
  framePosition = [5, 0],
  framePlane = XZ,
  fontPointSize,
  fontScale,
)