Freecad-Direct-Modeling-Public

Architecture reference for the unified edit-mode transform gizmo (translation arrows + rotation rings, transform spaces, x-ray rendering). Required reading before implementing any task in todo.md whose ID begins with GIZMO-.

Reference for the two-color (orange/blue) boolean system where IsSubtractive classifies inputs into groups and boolean operations combine them into a parent-child tree. Required reading before implementing any task in todo_bool.md.

Standardized pattern for creating interactive SDF primitive tools in the Direct Modeling workbench.

Template and rules for creating new SDF primitive field classes in core/sdf/sdf/. Required reading before implementing any new SdfField subclass.

Reference for converting SVG path data (M L H V C S Q T A Z) and shape elements (rect, circle, ellipse, line, polyline, polygon) into cubic Bezier segments with no rasterization. Required reading before implementing svg_importer.py.

Convention for registering primitive-specific GLSL inside the primitive's own .py file. Required reading before editing any to_glsl/to_glsl_2d method.

FreeCAD BSpline API reference and to_glsl() contract for SdfNurbsCurveField and SdfNurbsSurfaceField — tasks NS-001..NS-008 in todo_arch_refactor.md.

Interface contract, data layout, and mesher integration patterns for SdfOctreeCache — the hierarchical CPU evaluator that replaces np.meshgrid.

Reference for replacing the dense numpy SDF bake path with OpenVDB sparse level sets. Required reading before implementing VDB-* tasks in todo_vdb.md.

Reference for the SimulatorGL-derived SSAO upgrade to dm_scene_ray_march_renderer.py. Covers GLProgram/GLFramebuffer ctypes helpers, 4-pass FBO pipeline inside a SoCallback, G-buffer MRT layout, SSAO kernel math, and uniform plumbing.

Patterns for the OpenVDB sparse level-set SDF pipeline (replaces all dense numpy/GLSL paths).

Resources for OpenVDB, tree-based sparse volumes, and Ken Museth's publications.

Patterns for the new single-click primitive creation flow (spawn default + immediate edit) and edit-mode controls (Z/Ctrl/Shift). Required reading before implementing any task in todo_primitive_flow.md.

Architecture of the dual Qt/Coin3D event pipeline and the target single-owner design. Required reading before editing input_manager.py, dm_base.py, or dm_tool_manager.py.

Coordinate frame contract, helper method signatures, and invariants for the primitive tool refactor (todo_refactor.md). Required reading before implementing RF-* tasks.

Reference for renderer optimizations: screen-space adaptive cell size, dirty-flag incremental baking, camera sensor, and fragment shader stepping. Use when working on dm_scene_ray_march_renderer.py performance.

Reference for the renderer/meshing separation refactor. Covers the new RayMarchCellSize setting, normal kernel fix, and complete removal of meshing settings from all locations except cmd_sdf_export.py.

DEPRECATED — use dm_todo_format/SKILL.md instead. This skill has been merged into the more comprehensive dm_todo_format skill.

Reference for adding GLSL shaders to Coin3D scene graphs via pivy. Required reading before creating or modifying DMRayMarchRenderer or any code that uses SoShaderProgram.

How primitives store and render their additive/subtractive mode. Required reading before implementing any additive/subtractive toggle or per-field color rendering.

Reference for the to_glsl() contract, return format, GLSL naming conventions, and how the formulaic SDF rendering pipeline works. Required reading before implementing any to_glsl() method or modifying glsl_assembler.py.

Reference for the mesher class hierarchy, output format, timer instrumentation, and SdfField API. Required reading before modifying any mesher or adding mesh optimization passes.

Reference for writing GLSL 3.30 shaders in Coin3D via pivy. Required reading before modifying ray march renderers or creating new GPU shaders. Covers GLSL 3.30 syntax, Coin3D compatibility profile workarounds, texture format migration, and SoTexture3 3D texture usage.

Reference for the Coin3D scene graph structure of the GPU ray march renderer. Required reading before modifying dm_ray_march_renderer.py.

Pattern for single-RMB tool close. Required reading before editing on_button3_down or any tool's finish() method.

Reference for how Coin3D rendering is structured across the three geometry types (NURBS curves, SDF SDF, WorkPlane). Required reading before adding a new display type or modifying DMViewProvider.

Architecture reference for the scene-level ray march renderer that combines all SDF fields into a single baked 3D texture atlas and renders them with one full-screen quad. Covers the singleton lifecycle, field registry, combined baking, depth compositing, and how it replaces per-object DMRayMarchRenderer instances. Generic — works with any SDF, no per-primitive GLSL formulas.

Reference for how SDF boolean operations compose SdfField trees and how primitives are shortcuts for adding/subtracting from arbitrary SDF shapes. Required reading before modifying cmd_boolean.py or primitive tools to work with SDF fields.

Sphere-tracing ray march for CPU-side SDF hit detection. Required reading before implementing H-001..H-005 in todo_sdfhittest.md. Covers AABB slab test, ray_march signature, get_sdf_hit contract, and integration points.

Reference for the marching squares SDF slicer, DM curve compatibility requirements, and the fit_dm_curve contract. Required reading before implementing or modifying sdf_slicer.py.

Reference for the SDF-to-Mesh conversion tool. Covers where meshing belongs (dedicated tool, NOT render pipeline), the mesher API, output format, and how to create a Part.Shape from mesh data.

Reference for writing todo_*.md task lists for this project. Required reading before creating a new todo file or adding tasks to an existing one. Covers document structure, task format, dependency ordering, and when to create companion agent skills.

How to import FreeCAD Python modules from the AppImage when running agent scripts or standalone tests.

Architecture of the single-owner Qt-native input pipeline. Required reading before implementing the R-* tasks in todo_inputrefactor.md.

Enforces the "No Silent Fallbacks" rule for workplanes when modeling.

How to create dropdown/flyout toolbar buttons in FreeCAD using command groups. Required reading before adding grouped commands to InitGui.py.

Reference for correct depth buffer management when using custom GLSL shaders with gl_FragDepth in Coin3D. Covers opaque vs transparent render passes, SoDepthBuffer, gl_DepthRange, and common depth ordering bugs. Required reading before modifying depth-related code in DMRayMarchRenderer.

Reference for correct lighting calculations in custom GLSL shaders running under Coin3D. Covers coordinate space conventions, gl_LightSource transforms, and FreeCAD headlight behaviour. Required reading before modifying shading code in DMRayMarchRenderer.

Reference for how the PieMenu add-on replaces FreeCAD's native UI elements by shadowing commands, clearing toolbars, and using Qt event filters.

Reference for implementing full-screen quad raymarchers in Coin3D bypassing the standard view/projection matrices. Required reading before implementing R-006.