<languages/>
<translate>

<!--T:1-->
{{Macro
|Name=Macro Cut Object for Magnets
|Icon=Macro_Cut_Object_For_Magnets.png
|Description=Cut an object along a plane and add aligned magnet holes with surface collision detection. Creates two parts with perfectly aligned holes for embedding magnets that allow the parts to snap together.
|Author=Sean P. Kane
|Version=0.6.0
|Date=2026-01-12
|FCVersion=0.19+
|Download=[https://wiki.freecad.org/images/thumb/e/e3/Macro_Cut_Object_For_Magnets.png/48px-Macro_Cut_Object_For_Magnets.png ToolBar Icon]
|SeeAlso=[[Part_Slice|Part Slice]], [[PartDesign_Hole|PartDesign Hole]]
}}

==Description== <!--T:2-->

<!--T:3-->
This macro cuts a 3D object along a specified plane and automatically adds aligned magnet holes to both resulting pieces. The holes are positioned with intelligent collision detection to ensure they don't break through the outer walls of the object.

<!--T:4-->
This is particularly useful for:
* Creating multi-part prints that snap together with embedded magnets
* Splitting large objects for smaller 3D printer beds while maintaining alignment
* Adding magnetic closure mechanisms to enclosures and cases

<!--T:5-->
'''Key Features:'''
* Cut along preset planes (XY, XZ, YZ) or model datum planes
* Automatic hole placement with even distribution along the cut edge
* Surface collision detection prevents holes from breaking through walls
* Configurable hole diameter, depth, and count
* Preferred and minimum edge clearance settings
* Smart repositioning of holes when initial placement fails safety checks
* Creates PartDesign::Body objects with parametric Hole features
* Supports re-cutting already-cut objects (preserves existing holes)
* Automatically separates the two parts for easy viewing

==Usage== <!--T:6-->

<!--T:7-->
# Open a document with the object you want to cut
# Optionally select the object and/or a datum plane before running the macro
# Run the macro from '''Macro → Macros → CutObjectForMagnets → Execute'''
# In the dialog:
#* Select the body to cut from the dropdown
#* Choose the cut plane type (Preset or Model Plane)
#* For preset planes, set the offset from origin
#* Configure magnet hole parameters:
#** '''Diameter''': Hole diameter (should match your magnet size)
#** '''Depth''': Hole depth from cut surface
#** '''Number of Holes''': Total holes to create
#** '''Edge Clearance (Preferred)''': Ideal distance from hole edge to object surface
#** '''Edge Clearance (Minimum)''': Minimum acceptable clearance
# Click "Execute Cut"

[[File:MacroCutObjectForMagnetsDialog.png|400px|center]]


==Example== <!--T:8-->

This image shows a vase object in its original form, and after being cut multiple times with the macro. Magnets can then be inserted to object, and the object can be re-assembled. This example was to create a "breakable" vase for a theatrical stage performance, but there are many other potential uses as well.

[[File:CutObjectForMagnetsExample.png|400px|center]]

==How It Works== <!--T:9-->

<!--T:10-->
'''Cutting Process:'''
# Creates a large half-space box aligned with the cutting plane
# Uses boolean operations to split the object into two parts
# Creates PartDesign::Body containers for each half

<!--T:11-->
'''Hole Placement Algorithm:'''
# Calculates hole positions evenly distributed along the cut face perimeter
# For each position, validates against BOTH parts (not just one)
# Uses preferred clearance first, falls back to minimum if needed
# Checks for hole-to-hole spacing (minimum 2x diameter)
# Repositions holes that fail safety checks using multiple strategies:
#* Reduced clearance at same position
#* Increased inset from edge
#* Alternative positions along the perimeter

<!--T:12-->
'''Safety Features:'''
* Creates test cylinders to check if holes would break through walls
* Validates each hole against both the top and bottom parts
* Skips holes that cannot be safely placed
* Reports repositioned and skipped holes in the console

==Parameters== <!--T:13-->

<!--T:14-->
{| class="wikitable"
! Parameter !! Description !! Default
|-
| Plane Type || "Preset Plane" (XY/XZ/YZ) or "Model Plane" (datum plane) || Preset Plane
|-
| Offset || Distance from origin for preset planes || 0 mm
|-
| Diameter || Magnet hole diameter || 3 mm
|-
| Depth || Hole depth from cut surface || 3 mm
|-
| Number of Holes || Total holes to create || 6
|-
| Edge Clearance (Preferred) || Ideal distance from hole edge to object surface || 2 mm
|-
| Edge Clearance (Minimum) || Minimum acceptable clearance (used during repositioning) || 0.5 mm
|}

==Requirements== <!--T:15-->

<!--T:16-->
* FreeCAD 0.19 or later
* An object with a solid shape (Part or PartDesign body)
* For model plane mode: a datum plane or object with planar faces

==Installation== <!--T:17-->

<!--T:18-->
# Download the macro file: [[Media:CutObjectForMagnets.FCMacro|CutObjectForMagnets.FCMacro]]
# Copy the file to your FreeCAD macro directory:
#* '''macOS''': {{FileName|~/Library/Application Support/FreeCAD/Macro/}}
#* '''Linux''': {{FileName|~/.local/share/FreeCAD/Macro/}}
#* '''Windows''': {{FileName|%APPDATA%/FreeCAD/Macro/}}
# Optionally, download the toolbar icon and place it in the same directory

==Tips== <!--T:19-->

<!--T:20-->
* '''Magnet sizing''': Measure your magnets carefully. Common sizes are 3mm, 5mm, and 6mm diameter.
* '''Add tolerance''': Consider adding 0.1-0.2mm to the diameter for easier magnet insertion.
* '''Depth planning''': Set hole depth slightly deeper than magnet height to ensure flush or recessed fit.
* '''Edge clearance''': For thin-walled objects, reduce the preferred clearance but keep minimum clearance high enough to prevent wall breakthrough.
* '''Re-cutting''': The macro detects existing magnet holes and preserves them when cutting already-cut parts.

==Source Code== <!--T:21-->

<!--T:22-->
The full source code is hosted on GitHub:
* [https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Cut_Object_for_Magnets/CutObjectForMagnets.FCMacro CutObjectForMagnets.FCMacro on GitHub]

==Script== <!--T:23-->

<!--T:24-->
ToolBar Icon [[Image:Macro_Cut_Object_For_Magnets.png]]

</translate>

'''Macro_Cut_Object_For_Magnets.FCMacro'''

- https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Cut_Object_for_Magnets/CutObjectForMagnets.FCMacro

==Links== <!--T:25-->

<!--T:26-->
* [https://spkane.github.io/freecad-robust-mcp-and-more/ Full Documentation] - Complete guides and tutorials
* [https://github.com/spkane/freecad-robust-mcp-and-more GitHub Repository] - Source code and issue tracker
* [[Part_Slice|Part Slice]] - FreeCAD's built-in slice tool
* [[PartDesign_Hole|PartDesign Hole]] - Parametric hole feature documentation
* [[PartDesign_Body|PartDesign Body]] - Body container documentation

[[Category:Macros{{#translation:}}]]
[[Category:User Documentation{{#translation:}}]]
[[Category:Addons {{#translation:}}]]
