FreeCAD AdaptiveGrid

An adaptive XY ground grid for the Part and PartDesign workbenches in FreeCAD — inspired by the viewport grids of Fusion 360 and Blender.

Features

• Zoom-adaptive spacing — grid cells follow a 1-2-5-10 ladder (… 1 mm → 2 mm → 5 mm → 10 mm → 20 mm …) so they always stay a sensible size on screen (≥ 15 px, same threshold as FreeCAD's native Sketcher grid).
• Part-size-adaptive extent — the grid starts at 100 × 100 mm and grows to stay ~20 % larger than the XY footprint of your visible objects.
• Scale indicator — a small overlay in the bottom-right corner of the 3D view shows the current cell size (e.g. 5 mm).
• Stays out of the way — the grid only shows in Part and PartDesign, hides automatically while you edit a sketch (FreeCAD's native adaptive Sketcher grid takes over), and never interferes with View Fit (it doesn't inflate the view's bounding box).
• Zero configuration — loads at startup, works for every new or opened document.
• Fail-safe by design — every entry point is exception-guarded and the addon disables itself after repeated errors; it can never prevent FreeCAD from starting.

Installation

Clone this repository into your FreeCAD user Mod directory and restart FreeCAD:

Platform	Mod directory
Linux	~/.local/share/FreeCAD/Mod/
Linux (flatpak)	~/.var/app/org.freecad.FreeCAD/data/FreeCAD/Mod/
Windows	%APPDATA%\FreeCAD\Mod\
macOS	~/Library/Application Support/FreeCAD/Mod/

cd <your Mod directory>
git clone https://github.com/francoisbordas/FreeCAD-AdaptiveGrid.git AdaptiveGrid

Note: on FreeCAD 1.x the versioned directory (e.g. FreeCAD/v1-1/Mod/) also works.

Tested with FreeCAD 1.1.1. Requires FreeCAD 1.0+.

How it works

• A Coin3D line grid (SoLineSet under an SoSkipBoundingGroup) is inserted into each 3D view's scene graph — one instance per view.
• An SoNodeSensor attached to the camera detects zoom changes (debounced, 100 ms); geometry is only rebuilt when the spacing step or extent actually changes.
• A document observer tracks object changes to keep the grid ~20 % larger than the model footprint (debounced, 250 ms).
• Grid visibility is a cheap SoSwitch flip on workbench change / sketch edit.

Roadmap

• Optional grid snapping — the spacing API is already exposed:

  import AdaptiveGridCore
  m = AdaptiveGridCore.get_manager()
  m.current_spacing()      # active cell size in mm
  m.snap_point(vector)     # round a vector's X/Y to the nearest grid node
  m.grid_info()            # full state dict

Contributing

Issues and pull requests are welcome.

License

CC0 1.0 Universal — public domain. Do whatever you want with it.

This addon was written with Claude (Anthropic).