Dimension (Unified)¶

In one sentence: A smart, context-sensitive constraint tool that automatically detects whether to apply a distance, radius, diameter, or angle constraint based on what you have selected — and lets you cycle through types with the M key.

Overview¶

Workbench: Sketcher · Menu: Sketch → Sketcher constraints → Dimension
Toolbar: Sketcher Constraints · Shortcut: D

The unified Dimension tool (Sketcher_Dimension) was introduced in FreeCAD 1.0 as the recommended way to add dimensional constraints. It replaces the need to remember separate shortcuts for Distance, Radius, Angle, etc. by detecting the appropriate type from the current selection and offering a one-click confirmation or a M-key cycle to switch between available types.

Driving vs Reference mode: Every dimensional constraint, including those created by the unified Dimension tool, can be toggled between driving (controls the geometry) and reference (reads but does not constrain). See the deep dive below.

Intuition¶

Think of Dimension as a universal measuring tape that also sets the measurement: select what you want to measure, press D, and the tool figures out whether you are measuring a length, a radius, or an angle. If it picks the wrong type, press M to cycle to the next available type for your selection.

The value dialog appears immediately with the current measurement pre-filled. Type the desired value and confirm. The constraint is applied.

When to use it¶

Any time you need to set a numeric value on sketch geometry — this is now the primary constraint entry point.
Select a single line → distance along the line.
Select a circle or arc → radius (or cycle with M to diameter).
Select two lines → angle between them.
Select two points → point-to-point distance (or horizontal/vertical components with M).
You want to toggle a dimension between driving and reference without using the dedicated toggle tool.

When NOT to use it¶

You need a very specific constraint type and know the exact shortcut — using the dedicated tool (K, R for Radius, L for Horizontal Distance, etc.) is faster for experienced users.
You need a collinear or parallel constraint — those are geometric, not dimensional; use the dedicated geometric constraint tools.

Step-by-step walkthrough¶

Select geometry — a line, circle, arc, two lines, two points, or a point and a line.
Press D or activate Dimension from the toolbar.
A dimension preview appears on the geometry. The tool auto-selects the most appropriate constraint type.
If the wrong type is shown, press M to cycle through available types for the current selection (e.g. straight distance → horizontal distance → vertical distance, or radius → diameter).
Click to place the dimension label at a convenient location.
A value dialog appears with the current measurement pre-filled. Edit the value if needed and click OK (or press Enter).

Tip

You can leave the pre-filled value unchanged and just click OK — this sets the constraint to the current measurement, effectively locking it in place without changing the geometry.

Parameters¶

Parameter	Type	Default	Description
Constraint value	Distance / Angle / Radius	Current measurement	The numeric value to enforce.
Driving / Reference	Toggle	Driving	Whether the constraint controls geometry or just reads its value.

Driving vs Reference mode in depth¶

Every dimensional constraint can operate in one of two modes. Understanding the difference prevents the most common source of solver conflicts in Sketcher.

Driving (default)¶

A driving constraint owns the value — it tells the solver what the measurement must be, and the solver moves geometry to satisfy it. If you type 25 mm, the sketch element is repositioned so that the measurement equals exactly 25 mm.

Use driving mode when:

You are defining the design intent of your sketch (the actual sizes you want).
You want to fully constrain the sketch (green elements, zero degrees of freedom).
You intend to use the dimension value as a parameter that other features will reference.

Watch out for: Adding a driving constraint that conflicts with an existing constraint (e.g. you already have a coincident + horizontal constraint that fixes the distance) produces a redundant constraint (shown in red). Delete one of the competing constraints instead of switching to reference mode.

Reference (aka Construction/Inspection dimension)¶

A reference constraint reads the current measurement — it does not constrain geometry. The value shown is computed from whatever the geometry currently is; if the geometry moves, the value updates. Reference dimensions are shown in blue by default.

Use reference mode when:

You want to verify a computed dimension without adding a constraint (e.g. check the diagonal of a rectangle that is already fully constrained by its width and height).
The constraint would be redundant but you want the value visible for reference.
You are communicating a derived measurement to a downstream reader of the sketch.

Watch out for: Reference constraints do not constrain geometry — if you rely on them to control a shape, the sketch will remain under-constrained. Changing the displayed value in the UI has no effect when the constraint is in reference mode.

Toggling between modes¶

During constraint creation, click the Reference radio button in the value dialog before confirming.
After creation, select the constraint and press K+X (Toggle Driving Constraint) to flip it.
Alternatively right-click the constraint label in the viewport → Toggle driving.

Dimension type auto-detection¶

The type the Dimension tool selects depends on your selection:

Selection	Default type	`M` cycles through
1 line	Line length (distance)	Horizontal distance → Vertical distance
1 circle	Radius	Diameter
1 arc	Radius	Diameter
2 points	Point-to-point distance	Horizontal distance → Vertical distance
2 lines	Angle between them	—
1 point + 1 line	Distance from point to line	—
1 line + 1 arc	Angle at tangent point	—

Advanced usage¶

Setting reference (inspection) dimensions¶

During step 6 (the value dialog), click the Reference radio button before confirming. The dimension is shown in blue and does not constrain geometry. This is useful for checking a derived length or angle without adding a constraint that could conflict.

Formula-driven dimensions¶

The value field accepts FreeCAD formula expressions. Type =Spreadsheet.Width to drive the dimension from a spreadsheet cell, enabling full parametric design.

Batch dimensioning¶

You can select multiple geometry elements before pressing D; Dimension will apply a constraint to each selected element in sequence, prompting for a value each time.

Common mistakes and pitfalls¶

Dimension shows in red (over-constrained)

Cause: The value you set conflicts with an existing constraint that already determines this measurement.
Fix: Delete one of the conflicting constraints. The Dimension tool highlights which are redundant.

Dimension cycled to the wrong type with M

Cause: You pressed M one too many times and went past the desired type.
Fix: Press M again to cycle back, or press Esc and re-apply from scratch.

Reference dimension shows 0 or a wrong value

Cause: The geometry has not been solved to a final position yet (the sketch is under-constrained), so the reference dimension reads the current floating position.
Fix: Fully constrain the sketch first, then add reference dimensions to read derived values.

Python API¶

Minimal example¶

import FreeCAD as App
import Sketcher
import Part

doc = App.activeDocument()
sketch = doc.getObject("Sketch")

# Add a line
idx = sketch.addGeometry(
    Part.LineSegment(App.Vector(0, 0, 0), App.Vector(30, 0, 0)), False)

# Apply a driving distance constraint (equivalent to Dimension → distance)
sketch.addConstraint(Sketcher.Constraint("Distance", idx, 30.0))

# Apply a reference distance constraint (blue, non-driving)
sketch.addConstraint(Sketcher.Constraint("Distance", idx, 30.0))
# Set the last constraint to reference mode:
last = len(sketch.Constraints) - 1
sketch.setDriving(last, False)

doc.recompute()

Key method¶

sketch.setDriving(constraintIndex, isDriving)
# isDriving=True  → driving (controls geometry)
# isDriving=False → reference (reads geometry)