Path 3DSurface

Description
This tool creates a new 3D Surface Operation. The 3D Surface operation uses the entire top surface of the 3D Model to generate G-Code for the Job. Currently, within the operation's settings there is no functionality to select specific areas, faces, or regions of the Job base. The operation is applied to the entire surface of the Job base.

The 3D Surface Tool interfaces to OCL.pyd, a 3rd party Open Source module titled OpenCamLib, that generates tool paths from a 3D Model. OpenCamLib is not integrated directly into FreeCAD to ensure their license is not violated.

Note: In order to use the 3D Surface operation you must:
 * 1) Properly install OpenCamLib.
 * 2) Enable Experimental Features for the Path Workbench.

Usage
Usage instructions for multiple variations of the 3D Surface operation are presented here.

Basic Operation

 * 1) Press the  icon, or select the 3D Surface tool from the Path menu.
 * 2) Select the tool controller for the Operation from the Tool controller dialogue pop up window.
 * 3) Adjust the operation depths as needed in the Depths tab: Start Depth, Finish Depth, Step Down.
 * 4) Make adjustments in Heights tab if needed.
 * 5) Configure settings in the Operations tab:
 * 6) Select an operation algorithm: OCL Dropcutter or OCL Waterline.
 * 7) Choose the BoundBox: Stock or BaseBoundBox
 * 8) Add additional BoundBox Extra Offset to X and Y as desired
 * 9) Set the Drop Cutter Direction: X or Y. This is the linear direction the cutter(spindle) will travel.
 * 10) Add a Depth Offset value if you wish to leave a specified thickness of material on the surface.
 * 11) Set the Sample Interval used for the OCL scan.
 * 12) Set the Step Over value as a percentage of the diameter of the Tool.
 * 13) Optimize Output is enabled by default.  It is only a linear path optimization. Disabling will yield a longer gcode result and likely increase cut time.
 * 14) If you wish to preview the result before accepting the settings, click Apply
 * 15) Click OK button to confirm and generate paths.

To achieve different, or more complex, effects, adjust additional operation properties within the Data tab of the Properties View for the operation.

Multi-pass Scans

 * 1) Create a Basic Operation as described above. Multi-pass is available for both Algorithms.
 * 2) In the Properties list of the operation, locate the Algorithm section.
 * 3) Toggle the  property to Multi-pass to achieve the layering(step-down, multi-pass) effect.

Rotational Scans (4th-axis)

 * 1) Create a Basic Operation as described above using the OCL Dropcutter algorithm.
 * 2) Locate the Data tab and Properties View for the new 3D Surface operation.It is recommended that you set the desired rotation properties all at once before . This is done by clicking the ENTER key immediately after changing a property setting. This will allow you to change and save multiple properties before  the operation.
 * 3) In the Rotation section set  to the correct setting.
 * 4) Adjust the following settings as needed:
 * 5) * In the Algorithm section, change to the axis of travel for the cutter(spindle).
 * 6) * In the Algorithm section, set to single or mulit-pass.
 * 7) * In the Rotation section, set to the desired axis.
 * 8) * In the Rotation section, adjust to start index(angle) [0-360].
 * 9) * In the Rotation section, adjust to stop index(angle) [0-360].
 * 10) * In the Rotation section, set to the offset index(angle) [0-90]. (Used for ball mill cutters)
 * 11) With rotation-related properties set as needed, in the Algorithm section change the  from Planar to Rotational.
 * 12) Click the  icon in the tool bar.
 * 13) Wait for the results...

Notes About Rotational Scans

 * Rotational scans require much more time and processing than Planar scans. Factors affecting processing time include: Sample Interval, Step Over, tool diameter, and model size.  Again, rotational scans can take a long time.  Some might take 3, 5 or 10 minutes or longer.
 * It is recommended for time purposes that you not recompute a rotational scan after every property change; rather, use the 'change all settings' with ENTER key technique mentioned in Step 2 above, then recompute the operation.
 * The operation is still considered an 'experimental feature as of 2019-06-25. As such, it may contain a few bugs yet to be clearly identified.  Please report bugs and issues in the FreeCAD Path/CAM Forum.
 * The OCL Waterline algorithm does not support rotational scans.

Available Tool (Cutter) Shapes
This 3D Surface op currently uses OpenCamLib [OCL] to extract paths from the part base. As such, a tool setting translation is required between the FreeCAD tool controller and OCL in order to complete the scan with your chosen tool(cutter) shape.

These tool shapes are respected and available for this 3D Surface operation:


 * End mill
 * Ball end mill
 * Bull nose end mill
 * Chamfer bit
 * Engraver

Should you choose to run the path simulator in the Path Workbench, it only uses the standard end mill to simulate paths. Therefore, you will not see tool-shape-specific material removal. Material removal is shown using the end mill shape. NOTE: As of May 2019, only the End Mill has any type of testing to determine accuracy of the FreeCAD-to-OCL tool settings translation. Please post any feedback for non-end-mill usage to the Path/CAM section in the FreeCAD forums.

Properties
 Note : Not all of these Properties are available in the Task Window Editor. Some are only accessible in the Data tab of the Properties View panel for this Operation.

Algorithm

 * : The library to use to generate the path
 * : Should the operation be limited by the stock object or by the bounding box of the base object
 * : The direction along which dropcutter lines are created
 * : Additional offset to the selected bounding box - use sub-properties to set values
 * : x distance value
 * : y distance value
 * : z distance value
 * : The completion mode for the operation: single or multi-pass
 * : Planar: Flat, 3D surface scan. Rotational: 4th-axis rotational scan.

Base
Note: It is suggested that you do not edit the Placement property of path operations. Rather, move or rotate the Path Job model as needed.


 * : Overall placement[position and rotation] of the object - with respect to the origin (or origin of parent object container)
 * : Angle in degrees applied to rotation of the object around Axis property value
 * : Axis(one or multiple) around which to rotate the object, set in sub-properties: x, y, z
 * : x axis value
 * : y axis value
 * : z axis value
 * : Position of the object, set in sub-properties: x, y, z - with respect to the origin (or origin of parent object container)
 * : x distance value
 * : y distance value
 * : z distance value
 * : User-provided name of the object (UTF-8)

Depth

 * : The height needed to clear clamps and obstructions
 * : Final Depth of Tool- lowest value in Z
 * : The above which Rapid motions are allowed.
 * : Starting Depth of Tool- first cut depth in Z
 * : Incremental Step Down of Tool

Path

 * : make False, to prevent operation from generating code
 * : An optional comment for this Operation
 * : The direction that the toolpath should go around the part: Climb(ClockWise) or Conventional(CounterClockWise)
 * : Defines the Tool controller used in the Operation
 * : Clearing pattern to use
 * : Identify cutter boundary for operation.
 * : User assigned label

Rotation

 * : Automatically attempt Inverse Angle if initial rotation is incorrect.
 * : Set the cutter (spindle) tilt angle.
 * : Enable rotation to gain access to pockets or areas not normal to Z axis.
 * : Set fixed index for rotation.
 * : Select indexing mode: auto = automatic angle detaction; fixed = user set angle.
 * : Inverse the angle of the rotation.   Example: change a rotation from -22.5 to 22.5 degrees.
 * : Reverse orientation of Operation by 180 degrees.
 * : Set the axis for model rotation.
 * : Start index(angle) for rotation
 * : Stop index(angle) for rotation
 * : Stop index(angle) for rotation

Surface

 * : Z-axis offset from the surface of the object
 * : Enable optimization which removes unnecessary points from G-Code output
 * : The Sample Interval. Small values cause long wait times
 * : Step over percentage of the drop cutter path

Waste

 * : Ignore areas that proceed below specified depth.
 * : Depth used to identify waste areas to ignore.
 * : Cut through waste to depth at model edge, releasing the model.

Tasks Window Editor Layout
Descriptions for the settings are provided in the Properties list above. This section is simply a layout map of the settings in the window editor for the Operation.

Base Location

 * Add: adds selected element(s) which should be the base(s) for the path(s)
 * Remove: remove the selected item(s) in the Base Location list
 * Edit: clear all items in the Base Location list