How to Create FreeCAD TechDraw Sheets with Codex

A useful technical drawing tells someone how to interpret a part: which face they are looking at, where the holes belong, what the dimensions mean, and which revision they have. FreeCAD’s TechDraw workbench brings those details onto a drawing sheet linked to the model.

Codex can help prepare the Python macro that builds that sheet. In this workflow, you review the macro and run it inside FreeCAD, then inspect the resulting views, dimensions, and title block. FreeCAD performs the CAD operations; you decide whether the drawing communicates the part correctly.

Source: FreeCAD News / Jo Hinchliffe

We will follow one mounting plate from an existing model to an A4 landscape sheet, an editable native document, and a PDF checked against the saved drawing. A small revision will then test whether the dimensions still reference the intended geometry.

For recurring drawing work, use a Vagon cloud workspace to keep Codex, FreeCAD, and the project together while your everyday computer stays available for other tasks.

Define the Sheet Before Asking Codex to Build It

Start with a drawing brief that Codex can translate into specific objects and checks. For this example, use an existing rectangular plate measuring 80 mm along X, 50 mm along Y, and 6 mm along Z. Two 8 mm through holes have centers at X = 20 and 60 mm, both at Y = 25 mm, measured from the plate’s lower-left corner in the XY plane.

Confirm those values against your source model. They define our instructional example; use your own approved dimensions when drawing another part.

Specify the measurements the reader must recover: overall length, width, thickness, both hole diameters, and each hole center’s horizontal and vertical location from the chosen reference edges. The 40 mm center spacing follows from those locations; avoid adding it as another controlling dimension without a reason.

TechDraw’s projection groups support first-angle and third-angle arrangements. Choose the convention before placing views, then keep the arrangement and sheet identification consistent.

Leave material, general tolerances, and approval fields unfilled until you have authorized values. This first sheet establishes geometry and presentation; production requirements need their own review.

Give FreeCAD and Codex Their Own Drawing Workspace

If you prepare drawings regularly, give the job a dedicated Vagon computer for Codex. Run FreeCAD, Codex CLI, and the project copy inside that cloud desktop. Drawing generation and model recomputes then use the cloud computer’s resources while your everyday computer remains available for email, research, or other design work. You can inspect and finish the drawing on the same desktop where it was created.

We will use Ubuntu for this workflow. Create the cloud computer, connect to its desktop, and install FreeCAD if your selected environment does not already include it. The research baseline is FreeCAD 1.1.4; record your installed version from Help → About FreeCAD before asking Codex to write application-specific code.

Open FreeCAD and confirm that the TechDraw workbench loads. For this small plate, prioritize a working application setup and enough memory for your model; the example does not establish a need for a larger GPU.

Next, follow the official Codex CLI installation instructions in a terminal on the Vagon desktop. Sign in with your own OpenAI access. Installing the CLI there puts its file operations and commands on the cloud machine.

Create a project folder in that terminal:

mkdir -p ~/techdraw-plate/{source,working,macros,exports}
cd

mkdir -p ~/techdraw-plate/{source,working,macros,exports}
cd

mkdir -p ~/techdraw-plate/{source,working,macros,exports}
cd

Transfer plate-source.FCStd into source, open it in FreeCAD, and use Save As to create working/plate-techdraw.FCStd. Keep the source unchanged. Store generated .FCMacro files in macros and drawing PDFs in exports.

Codex will prepare macro files in this folder. You will review and execute them inside FreeCAD, where the application’s Python modules and open document are available. This workflow does not require an MCP server, and starting Codex does not automatically connect it to the FreeCAD session.

Begin with one useful task: ask Codex to prepare a report-only inventory macro for the working document. The next step will establish the model and template facts that the drawing macro needs.

Inspect the Model and Template Inside FreeCAD

Before generating drawing objects, give Codex facts from the working document. A file path identifies the project, but the macro also needs the internal name of the solid it will project. A displayed label such as “Plate” may be shared by several objects.

Ask Codex to prepare the inventory macro:

Create macros/inspect_plate.FCMacro for execution inside FreeCAD. Inspect the active document without changing objects, recomputing, or saving it. Report its file path, internal document name, and FreeCAD version. List objects with nonempty shapes, including internal Name, Label, TypeId, placement, bounding-box limits and sizes in millimeters, and solid count. For each PartDesign Body, identify its Tip. Locate Mod/TechDraw/Templates/ISO/A4_Landscape_ISO5457_advanced.svg under FreeCAD’s resource directory and read its SVG dimensions and editable field names without creating document objects. Report missing data explicitly. Write the report to ~/techdraw-plate/exports/model-inventory.json, expanding the home directory, and print its location.

Review the generated file, then use Macro → Macros in FreeCAD to browse to it and execute it. Confirm that the reported document path ends in working/plate-techdraw.FCStd.

Select the final Body in the model tree and compare it with the report. Its shape should contain the finished plate, including both holes. Earlier pads and pockets can also have valid shapes; projecting those alongside the Body would duplicate or expose intermediate geometry. Record the chosen Body’s internal name for the drawing macro.

Source: FreeCAD News / Jo Hinchliffe

Check the expected 80 × 50 × 6 mm envelope. Bounding-box dimensions alone do not establish hole diameter or location; inspect the hole features or measure their geometry separately.

The proposed A4 template includes fields such as title, drawing_number, revision_index, and scale. Use the installed file’s reported keys and path. If it is missing, locate a suitable installed template and inspect that file before proceeding.

Finally, ask Codex to read the inventory JSON and summarize the selected source object and template. Resolve discrepancies before it writes the drawing macro.

Build the Page and Arrange Consistent Projection Views

With the source object and template confirmed, ask Codex to create macros/build_plate_sheet.FCMacro. Keep the document path, source object name, template path, projection convention, scale, and layout settings together near the top of the file. That gives the next drawing a small set of deliberate inputs to change.

Source: FreeCAD News / Jo Hinchliffe

Give Codex this assignment alongside the inventory report and your sheet brief:

Write a FreeCAD GUI macro for the confirmed working document and selected Body. Validate the document path, source object, and template file before changing anything. Create or reuse TD_PlatePage as a TechDraw DrawPage, TD_PlateTemplate as its DrawSVGTemplate, and TD_PlateViews as a DrawProjGroup. Reject existing objects with incompatible types or unrelated ownership. Add the group to the page before adding projections. Use Third Angle and Custom scale 1.0. Make the anchor look onto the XY face along Z, with X horizontal, and add two orthographic projections showing thickness. Reuse existing group members on subsequent runs. Initialize positions and spacing only for new objects; preserve existing layout and dimension-label positions unless an explicit re-layout option is enabled. Validate existing direction, scale, and projection settings; report mismatches rather than silently resetting them. Preserve the source geometry, unrelated pages, dimensions, and annotations. Recompute and report the generated objects and settings. Do not save or export automatically.

FreeCAD’s documented projection-group scripting sequence attaches the group to its page before adding projections. This lets the group obtain defaults from the page. Its member views share the group’s scale, so changing one overall scale setting keeps the orthographic set consistent.

Review the macro’s orientation settings before running it. For this plate, the intended broad-face view uses a direction along Z and an in-plane X direction along X. Ask Codex to use the installed API’s Direction and XDirection properties where applicable. The example’s anchor may be called “Front” internally even though it displays the plate’s XY face; judge it by the geometry and axes.

Run the macro through FreeCAD’s Macro dialog, then double-click TD_PlatePage in the tree. The broad view should show an 80 × 50 mm rectangle with two circular holes. The supporting views should reveal the 6 mm thickness. Elliptical holes or a foreshortened outline indicate that the main view is angled.

Source: FreeCAD Documentation

Check the group’s projection type and the placement of its secondary views together. A “Third Angle” setting does not excuse a manually rearranged layout that communicates another convention.

Move the group and adjust spacing until the views fit inside the border, clear of the title block. Leave room for dimensions. If positioning views manually, disable Auto Distribute so applying the group settings does not redistribute them. Save the accepted layout; normal macro runs must preserve it. Keep the configured scale and title block consistent with any approved scale change.

Source: FreeCAD News / Jo Hinchliffe

An isometric reference view is optional. Add it only if it helps explain the part and leaves enough space for dimensions. Give it a separate scale label if needed, and keep the dimensional work on the orthographic views.

Once the layout is readable, save the working document. Keep the generated macro alongside it so later adjustments can reproduce the chosen arrangement.

Attach Dimensions to the Geometry You Actually Mean

Add the first dimensions in FreeCAD and inspect their references before automating them. Select the broad view’s horizontal outer edge and use TechDraw → Dimensions → Insert Horizontal Dimension for 80 mm. Repeat with a vertical outer edge using the vertical tool for 50 mm. In a supporting view, dimension the 6 mm thickness.

The horizontal dimension tool measures horizontal separation; a general length between offset points can instead measure a diagonal. Choose the tool that expresses the intended direction.

Source: FreeCAD Documentation

Select each circular hole edge in the broad-face view and add a diameter dimension. Both should read 8 mm, with their arrows targeting the correct circles.

Source: FreeCAD Documentation

For the center locations, use FreeCAD’s documented center-mark selection method:

1. Select the broad-face view in the tree. In its View properties, under Decoration, set Arc Center Marks to true.

2. Clear the selection, then Ctrl-select the left hole’s center mark and the plate’s lower-left corner point in that view. Use Insert Horizontal Dimension. The separation should be 20 mm.

3. Select the same center and corner again, then use Insert Vertical Dimension for 25 mm.

4. Repeat for the right hole, using the same corner. Expect 60 mm horizontally and 25 mm vertically.

These selections use the projected circle centers. Do not substitute an arbitrary point typed at the expected coordinates. If a center cannot be selected, resolve its visibility or selection settings before continuing.

Source: FreeCAD News / Jo Hinchliffe

Before creating more dimensions, have Codex prepare an inspection-only macro that writes exports/dimension-map.json. For every existing dimension on TD_PlatePage, record its internal name, type, References2D, References3D, measurement mode, measured value, and X/Y label position. Serialize object references as document/object names and subelement identifiers. Run it inside FreeCAD, then give Codex the report and identify each dimension’s role.

Extend build_plate_sheet.FCMacro using this role-to-object mapping. Adopt the existing manual dimensions by internal name, verifying their type and references before reuse. Stop on missing objects, changed references, or ambiguous duplicates. Create only explicitly missing roles, and record their names in the mapping. Preserve label positions and keep Arbitrary Text disabled. Report measurements for review.

The dimension documentation distinguishes projected and true 3D measurements. Our orthographic views should show the intended lengths directly. Investigate a foreshortened value rather than replacing its displayed text.

Source: FreeCAD Documentation

Run the reviewed function, compare every dimension with the source model, and arrange the labels. The next run must retain those same objects, references, and positions. Save the checked result.

Complete the Title Block and Review the Sheet

Give the drawing an identity before exporting it. For this example, use “Mounting Plate” as the title, “PLATE-001” as the drawing number, and “A” as the revision. Mark its status as “For review” while production requirements remain unresolved.

Select TD_PlateTemplate and inspect its editable text fields. FreeCAD templates expose these as a key/value map. Have Codex add a metadata function to the existing macro that reads EditableTexts, changes only confirmed keys, and assigns the updated map back to the template. It should report missing keys instead of silently substituting another field.

Source: FreeCAD Documentation

For the selected template, map the title to title, drawing number to drawing_number, revision to revision_index, and review status to document_status. Set scale to the actual orthographic group scale. Treat this as a value to verify after layout changes; editable title-block text is not proof that a view uses that scale.

Remove any sample material, tolerance, author, or approval entries that could be mistaken for project instructions. Enter your actual creator name and issue date when appropriate. Keep unresolved engineering fields blank and retain the review status.

Before saving, inspect the whole page and then its crowded areas:

• Confirm that millimeter units and third-angle projection are clearly identified.

• Check that dimension text, arrowheads, and extension lines remain distinguishable at a practical reading size.

• Review hidden-line visibility, center indications, and leaders so each hole and thickness dimension has an unambiguous target.

Keep labels clear of the border and title block. Once the metadata matches the geometry and the page is readable, save working/plate-techdraw.FCStd for the export check.

Save the Native Drawing and Inspect the Exported PDF

Before exporting, select TD_PlatePage and check Keep Updated. When updates are suspended, the page can retain an earlier model state. Use Redraw Page when needed, recompute the document, and wait for the views to finish updating. Check the dimensions and title block again, then save.

Close and reopen working/plate-techdraw.FCStd. Open the drawing page and confirm that its views, dimensions, and editable title fields remain available. This checks the saved native document independently of the session that created it.

For PDF export, create macros/export_plate_pdf.FCMacro with the following code and run it inside FreeCAD after reopening the drawing page:

from pathlib import Path
import FreeCAD as App
import TechDrawGui

root = Path.home() / "techdraw-plate"
doc = App.ActiveDocument
expected = (root / "working/plate-techdraw.FCStd").resolve()
if doc is None or Path(doc.FileName).resolve() != expected:
    raise RuntimeError("Open the saved plate-techdraw working document.")
page = doc.getObject("TD_PlatePage")
if page is None or page.TypeId != "TechDraw::DrawPage":
    raise RuntimeError("The expected TechDraw page is missing.")
output = root / "exports/plate-techdraw-rev-a.pdf"
output.parent.mkdir(parents=True, exist_ok=True)
TechDrawGui.exportPageAsPdf(page, str(output))
App.Console.PrintMessage("Inspect PDF: " + str(output) + "\n")

from pathlib import Path
import FreeCAD as App
import TechDrawGui

root = Path.home() / "techdraw-plate"
doc = App.ActiveDocument
expected = (root / "working/plate-techdraw.FCStd").resolve()
if doc is None or Path(doc.FileName).resolve() != expected:
    raise RuntimeError("Open the saved plate-techdraw working document.")
page = doc.getObject("TD_PlatePage")
if page is None or page.TypeId != "TechDraw::DrawPage":
    raise RuntimeError("The expected TechDraw page is missing.")
output = root / "exports/plate-techdraw-rev-a.pdf"
output.parent.mkdir(parents=True, exist_ok=True)
TechDrawGui.exportPageAsPdf(page, str(output))
App.Console.PrintMessage("Inspect PDF: " + str(output) + "\n")

from pathlib import Path
import FreeCAD as App
import TechDrawGui

root = Path.home() / "techdraw-plate"
doc = App.ActiveDocument
expected = (root / "working/plate-techdraw.FCStd").resolve()
if doc is None or Path(doc.FileName).resolve() != expected:
    raise RuntimeError("Open the saved plate-techdraw working document.")
page = doc.getObject("TD_PlatePage")
if page is None or page.TypeId != "TechDraw::DrawPage":
    raise RuntimeError("The expected TechDraw page is missing.")
output = root / "exports/plate-techdraw-rev-a.pdf"
output.parent.mkdir(parents=True, exist_ok=True)
TechDrawGui.exportPageAsPdf(page, str(output))
App.Console.PrintMessage("Inspect PDF: " + str(output) + "\n")

The TechDraw GUI export API exports the specified page. Run this in the application’s GUI environment; a system Python process is not a substitute. Repeating the export uses the same output filename, so preserve any earlier PDF you need before running it again.

Open the PDF in a separate viewer. Verify one landscape A4 page, 297 × 210 mm, with the complete border, title block, and all intended views. Compare the revision and dimension values with the reopened native sheet. Zoom into hole leaders, diameter symbols, and small text to catch clipping or font problems.

Viewer zoom does not establish drawing scale. If a physical 1:1 print matters, print at actual size without fit-to-page scaling and measure the known 80 mm span.

A successful export call establishes neither readable output nor agreement with the saved drawing. Keep the native file and inspected PDF together as the Rev A review package.

Rerun the Macro and Check a Revised Part

Move one dimension label and the view group, save, then run build_plate_sheet.FCMacro twice with re-layout disabled. Compare object identities, counts, references, and positions with dimension-map.json and the saved layout. Existing objects must remain in place without duplicates. Update the report after accepting layout changes.

Preserve the checked Rev A files. Use Save As to create working/plate-techdraw-rev-b.FCStd, then change the model’s controlling hole diameter from 8 to 10 mm. Keep the plate envelope and hole centers unchanged. Update the build macro’s expected document path and revision metadata before running it on this copy.

Recompute, update the drawing page, and inspect both diameter dimensions. Each should measure 10 mm, while the plate remains 80 × 50 × 6 mm and the hole locations remain unchanged. Check the referenced geometry even when a displayed value appears plausible.

If a dimension has lost its target, use Repair Dimension References, verify the new selection, and refresh the mapping. On a disposable copy, also move one hole center: its location dimensions must update correctly or be flagged for repair. Discard that test copy afterward.

Set the title-block revision to B, save, and reopen the native file. For the export macro, change both the expected document path to working/plate-techdraw-rev-b.FCStd and the output path to exports/plate-techdraw-rev-b.pdf. Inspect the new PDF against the reopened Rev B sheet.

Retain both revisions with the macros used to produce them. That gives the next change a known starting point and a clear record of what the drawing represents.

FAQs

Does Codex need an MCP server to create TechDraw sheets?

This workflow uses macro files that you execute inside FreeCAD. MCP becomes relevant when you want Codex to inspect or operate the live application through a compatible connector. It is not required for preparing the macro.

Can I use an imported STEP model?

Yes, provided the imported object contains suitable geometry for the drawing. Select that object as the source instead of assuming a PartDesign Body exists. The hole-diameter revision exercise requires an editable model or a separately prepared revised input.

Why does the macro fail when I run it with Python in the terminal?

These macros expect FreeCAD’s application environment. The export example also uses TechDrawGui and an open drawing page. Execute it through FreeCAD’s Macro dialog; installing an unrelated Python package does not provide that session.

Does changing the drawing scale change the model dimensions?

View scale controls how large the geometry appears on paper. It does not resize the source part. Check measured dimension values, title-block scale, and print scaling separately.

Is the exported PDF ready for manufacturing?

Only after the responsible reviewer confirms the necessary material, tolerances, finishes, notes, and approvals for the job. The example produces a review drawing and an editable source document; successful macro execution does not establish manufacturing completeness.