create/reference/ztools/TODO_ATTACHMENT_WORK.md

Datum Attachment Work - In Progress

Context

Implementing proper FreeCAD attachment for datum objects to avoid "deactivated attachment mode" warnings. The pattern is adding source_object and source_subname parameters to each datum function and using _setup_datum_attachment() with appropriate MapModes.

Completed Functions (in core.py)

Planes

• plane_offset_from_face - MapMode='FlatFace'
• plane_midplane - MapMode='TwoFace'
• plane_from_3_points - MapMode='ThreePointPlane'
• plane_normal_to_edge - MapMode='NormalToPath'
• plane_angled - MapMode='FlatFace' with rotation offset
• plane_tangent_to_cylinder - MapMode='Tangent'

Axes

• axis_from_2_points - MapMode='TwoPointLine'
• axis_from_edge - MapMode='ObjectXY'
• axis_cylinder_center - MapMode='ObjectZ'
• axis_intersection_planes - MapMode='TwoFace'

Points

• point_at_vertex - MapMode='Vertex'

Remaining Functions to Update (in core.py)

• point_at_coordinates - No attachment needed (explicit coordinates), but could use 'Translate' mode
• point_on_edge - Use MapMode='OnEdge' with MapPathParameter for position
• point_center_of_face - Use MapMode='CenterOfCurvature' or similar
• point_center_of_circle - Use MapMode='CenterOfCurvature'

After core.py Updates

Update datum_commands.py to pass source references to the remaining point functions:

• create_point_at_vertex - already done
• create_point_on_edge - needs update
• create_point_center_face - needs update
• create_point_center_circle - needs update

Pattern for Updates

1. Add parameters to function signature:

   source_object: Optional[App.DocumentObject] = None,
   source_subname: Optional[str] = None,
   

2. In the body section, use attachment instead of placement:

   if source_object and source_subname:
       support = [(source_object, source_subname)]
       _setup_datum_attachment(point, support, "MapMode")
   else:
       _setup_datum_placement(point, App.Placement(...))
   

3. Update datum_commands.py to extract and pass source references from selection.