Migrating and Updating Docs

scripts/addons/cam/ui/panels/info_panel.py

@@ -88,12 +88,24 @@ class CAM_INFO_Panel(CAMParentPanel, Panel):
             box = main.box()
             col = box.column(align=True)
             col.label(text="Estimates")
-            col.label(text=f"Time: {time_estimate}", icon="TIME")
+            row = col.split(factor=0.32)
+            title_col = row.column(align=True)
+            # title_col.alignment = "RIGHT"
+            value_col = row.column(align=True)
+            # value_col.alignment = "LEFT"
+
+            title_col.label(text="Time:", icon="TIME")
+            value_col.label(text=time_estimate)
 
             # Operation Chipload
             if self.op.info.chipload > 0:
-                col.prop(self.op.info, "chipload")
-                col.label(text=self.op.info.chipload_per_tooth, icon="DRIVER_ROTATIONAL_DIFFERENCE")
+                chipload = self.op.feedrate / (self.op.spindle_rpm * self.op.cutter_flutes)
+                chipload = f"{chipload:.5f}"
+                title_col.label(
+                    text=f"Chipload:",
+                    icon="DRIVER_ROTATIONAL_DIFFERENCE",
+                )
+                value_col.label(text=chipload)
             else:
                 pass
 
@@ -107,5 +119,6 @@ class CAM_INFO_Panel(CAMParentPanel, Panel):
 
                 cost_per_second = bpy.context.scene.cam_machine.hourly_rate / 3600
                 total_cost = self.op.info.duration * 60 * cost_per_second
-                op_cost = f"Cost: ${total_cost:.2f} (${cost_per_second:.2f}/s)"
-                col.label(text=op_cost, icon="TAG")
+                op_cost = f"${total_cost:.2f} (${cost_per_second:.2f}/s)"
+                title_col.label(text="Cost:", icon="TAG")
+                value_col.label(text=op_cost)

scripts/addons/docs/developers.rst

@@ -0,0 +1,20 @@
+Developer Guide
+******************
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   style
+   testing
+   workflows
+
+This section is for people who want to contribute code to BlenderCAM, people who want to modify the addon for their needs, or anyone who simply want to better understand what is happening 'under the hood'.
+
+:doc:`overview` offers a guide to the addon files and how they relate to one another.
+
+:doc:`style` gives tips on editors, linting, formatting etc.
+
+:doc:`testing` has information on how to run and contribute to the Test Suite.
+
+:doc:`workflows` contains an explanation of how the addon, testing and documentation are automated via Github Actions.

scripts/addons/docs/faq.md

@@ -0,0 +1,3 @@
+# FAQ
+
+What's the deal with airplane peanuts?

scripts/addons/docs/index.rst

@@ -10,47 +10,11 @@ This site serves as an introduction to Fabex, a free and open source extension f
 Fabex allows you to generate toolpaths and gcode files based on 3D objects or 2D Images within Blender.
 These files can then be sent to a CNC machine to cut your designs!
 
-User Guide
+Guides
 *****************
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   install
-   starting
-   panels
-   tools
-   profilepocket
-
-This section is for new users, containing basic info on how to install and use the extension.
-
-:doc:`install` contains instructions for downloading and installing Fabex and Blender.
-
-:doc:`starting` is a good place for newcomers to begin.
-
-:doc:`panels` gives descriptions of what each of the panels in the UI is for.
-
-:doc:`tools` offers an introduction to the various tools packaged with Fabex.
-
-:doc:`profilepocket` contains a step-by-step guide for completing these common operations.
-
-Developer Guide
-******************
-
-.. toctree::
-   :maxdepth: 1
-
-   overview
-   style
-   testing
-   workflows
-
-This section is for people who want to contribute code to BlenderCAM, people who want to modify the addon for their needs, or anyone who simply want to better understand what is happening 'under the hood'.
-
-:doc:`overview` offers a guide to the addon files and how they relate to one another.
-
-:doc:`style` gives tips on editors, linting, formatting etc.
-
-:doc:`testing` has information on how to run and contribute to the Test Suite.
-
-:doc:`workflows` contains an explanation of how the addon, testing and documentation are automated via Github Actions.
+   users
+   developers

scripts/addons/docs/install.md

@@ -1,22 +1,66 @@
 # Installation
 
-## Use CNC CAM extension for Blender from github 
+**FabexCNC** is an Extension for **Blender** version 4.21 and later.
 
-Using CNC CAM Blender extention from github is a great way to try out the newest features and fixes.  The latest build (dailybuild) of Blender can be used with the latest Master branch of CNC CAM extension and then you can live on the bleeding edge.
+> [!NOTE]
+> To use Fabex with Blender 4.1 and earlier use one of the blendercam.zip releases from the Github Releases page.
 
-## Obtaining Blender
-CNC CAM is an extension for Blender. It works now with Blender version 4.21 .
+## Get Blender
 
-You can download blender from here:
-https://www.blender.org/download/
+[Download Blender from the official site.](https://www.blender.org/download/)
 
-To install CNC CAM extension for Blender, download blendercam.zip 
+> [!NOTE]
+> If you are a Linux user, it is recommended that you download Blender from their website, and **NOT install via a Package Manager.**
+> Blender has elected to support only Python 3.11 for Extensions, so Fabex is packaged with dependencies that are only compatible with Python 3.11.
+> Since many distros will allow you to install Blender and Python separately this can lead to version mismatch and a broken Extension.
+> 
+> *For details on how to work around this issue, see the FAQ.*
 
-Stable: https://github.com/vilemduha/blendercam/releases
+## Get Fabex
 
-Experimental: https://github.com/pppalain/blendercam/releases
+### For Users
 
-*don't* extract it. In blender, go to preferences, Get Extension, and select 'Install from Disk' and select the blendercam.zip file you downloaded.  After Blender must be restarted to ensure the wheels are correctly installed.
+#### Stable Version
+[Download the Stable version here.](https://github.com/vilemduha/blendercam/releases)
+
+The Stable version will not have all the latest features right away, but it is more thoroughly tested and generally more reliable than the latest version. 
+
+_If you're not sure which version you want, then you probably want the Stable version!_
+
+#### Experimental Version
+[Download the Experimental version here.](https://github.com/pppalain/blendercam/releases)
+
+The Experimental version will have all the latest features, but is more likely to encounter bugs and errors and is recommended for more experienced users, developers and testers.
+
+> [!NOTE]
+> [The latest (Daily) build of Blender](https://builder.blender.org/download/daily/) can be used with the Experimental branch of FabexCNC to live on the bleeding edge!
+
+From the Releases page, download **fabexcnc.zip**.
+
+*(Don't extract it, Blender is expecting a .zip file!)*
+
+#### Install Fabex
+
+- Open **Blender**
+- Click **Edit** > **Preferences** > **Get Extension**
 
 ![image](https://github.com/user-attachments/assets/7776b3dd-2411-4348-b4d7-b0262f683f90)
+- Click the small arrow in the top right of the window, then click 'Install from Disk'
+
 ![image](https://github.com/user-attachments/assets/1bec6168-5b57-48c4-afe7-310664fa979d)
+- Select the **fabexcnc.zip** file you downloaded, then click **Install from Disk**
+- Blender may need to be restarted to ensure the dependencies are correctly installed.
+
+> [!NOTE]
+> If you experience difficulty installing the Extension, check out the FAQ for common installation issues and fixes, or try the Matrix chat for help from developers and other users.
+
+You're now ready to start using Fabex!
+
+If you're not sure what to do next, check out the Getting Started page.
+
+### For Developers
+If you intend to contribute to the Fabex codebase, or if you want to modify the Extension to suit your own needs, you may find that the installation method outlined above is not the best for rapid iteration and updates.
+
+For these users we recommend cloning the repository from Github, then creating a symlink (alias, shortcut) for the 'cam' folder and moving that into [Blender's Extension directory.](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)
+
+For more details, see the FAQ.

scripts/addons/docs/interface.md

@@ -0,0 +1,185 @@
+# Interface
+
+Fabex's user interface was designed to facilitate multiple different workflows, layouts and experience levels.
+
+Fabex can do a lot of things so we try to balance not overwhelming new users with giving access to the many parameters necessary for advanced users.
+
+**Interface** allows users to hide options below a certain level, simplifying the layout for beginners.
+- **Basic** - displays only necessary panels and options
+- **Advanced** - displays more panels and options
+- **Complete** - displays all Stable options
+- **Experimental** - all previous options, plus those marked EXPERIMENTAL
+
+**Layout** will rearrange where the panels are placed onscreen. 
+- **Modern** - splits the panels between the Properties and Sidebar areas 
+- **Classic** - preserves the original BlenderCAM layout
+- **User** - can be edited in Preferences
+
+**Shading** offers quick preset viewport settings for users unfamiliar with Blender's interface.
+- **Default** - standard Blender viewport shading
+- **Deluxe** - enables extra shading options to help view mesh details or organize comples scenes
+- **Clean Default** - same as Default with the Viewport Grid turned off
+- **Clean Deluxe** - same as Deluxe with the Viewport Grid turned off
+- **Preview** - enables HDRI and material shaders
+
+## Enter CNC/CAM Mode
+The main interface is arranged into a series of panels described below. 
+
+*(Most functionality can also be accessed through menus, pie menus or the Search operator, if you prefer.)*
+
+Fabex hides its many panels when it is not active. 
+
+To display them you need to enter CNC/CAM mode.
+
+In the **Properties** area, in the **Render** tab, set the **Render Engine** to **Fabex CNC/CAM**
+
+![Renderer selection](_static/RenderEngine.png)
+
+## Panels
+
+### [ Operations ]
+![CAM operations](_static/OperationsPanelSuzanne.png)
+- **Calculate Path & Export Gcode** - This calculates the operation which is currently selected in the cam operations list. The Button will stay selected until the calculation is completed.
+- **Simulate This Operation** - Works for 3 axis operations, but not for all. It creates a new object which shows the simulation - the subdivision of the object can be increased, and the resolution of the simulation also depends on simulation sampling raster detail, which is in the optimization panel
+- **Operation Name** - Select this field to change the name of the currently selected operation.
+- **File Name** - Name of the gcode file. The file extension used will be determined by the g-code post processor selected. See [Machine panel](Blendercam-Panel-Descriptions.md) for setting post processor.
+- **Data Source** - This can be either 1 object, a group of objects, or an image.
+  * **Object** - a Blender object.  This could be a mesh, or a curve.
+  * **Collection** - Objects can be combined into a Collection in the Outliner.
+  * **Image** - Open an image that will be used as a height/depth map.
+- **Object** - the blender object that will be used in the CAM operation. Select the object from a drop down list. Write it's name in the field, it should auto-complete and give a list of objects to select from.
+> [!NOTE] 
+> *If you change the object's name later on then you must also change it here. The field will turn red if the object can not be found.*
+
+### [ Machine ]
+![Cam machine](_static/MachineParameters.png)
+
+This panel sets up your machine and the settings are common in the whole file.
+You can also set up your machine and then save your default file with Ctrl+U command. This way you will always start with the settings you need.
+
+* **Post Processor** - this defines the formatting of the output file. If your machine is not in the list, you can try the ISO code, which is standardized Gcode
+* **Unit System** - Metric or Imperial
+* **Work Area** - if the Operation has a larger area than this, you will get a warning in the info panel
+* **Feedrate minimum/maximum** - this will limit your feed speeds set up in the feedrate panel.
+
+### [ Info ]
+![Cam Info & warnings](_static/InfoPanel.png)
+
+This panel will show any trouble found during the computation, estimated operation time, and chipload data
+
+
+### [ Operation Setup ]
+![Strategy](_static/OperationSetupPanel.png)
+
+- **Axis Count** - how many axes will be used _(Default is 3, additional axes should be enabled in the Machine panel first)_
+- **Strategy** sets one of the strategies.
+
+Depending on which **Strategy** is selected, the options will differ. Below is a sampling of some common settings *(see the Strategy page for a full list of options for each Strategy)*:
+* **Inverse Milling** - used if you want to mill a form directly from positive of the object. Does not work in exact mode. Only works for 3 axis strategies.
+* **Skin** - useful for roughing, leaves a layer on the surface for finishing
+* **Angle of Paths** - this rotates the parallel and cross strategies by the specified amount. Note that e.g. rotating by 90 changes the basic axis from X to Y
+- **Toolpath Distance**
+  * **Between** - also called Stepover
+  * **Along** - how dense will be the operation path. This can influence accuracy of the machining. 
+<!-- * **parallel step back** - this function is only for finishing pass, where you still have to cut some substantial amount of material, and want also to save the cutter. If you set up to climb movement, it goes with climb into material, then goes in the other direction one step back - this uses the back movement of the machine for finishing the surface. Note that this also means the cutting into material will happen with a rate which is 2x of distance between toolpaths If you don't know what this all means, don't use this function. !!!!!!!!!!!!MOVED TO MOVEMENT PANEL!!!!!!!!!-->
+* **Direction** - for block and spiral strategy, decides if the path progresses from inside or from outside
+* **Carve** 
+  * **Depth** - decides how deep below the surface will go the carve operation
+* **Outlines**
+  * **Don't Merge** - for cutout strategy. Does not merge outlines - this results into cutting in the object area! It is usefully when milling PCBs, where you don't need exact shape but need to separate areas with engraving.
+* **Bridges (Tabs)** - for cutout operation, places automatically bridges by the rules set by options that will appear after this is enabled: width, height, minimum per curve, distance.
+
+### [ Operation G-code ]
+![](_static/OperationGcodePanel.png)
+
+- **Output Header**
+- **Output Trailer**
+- **Dust Collector**
+- **Hold Down**
+- **Mist**
+
+### [ Optimization ]
+![Cam Optimization](_static/OptimisationPanel.png)
+
+This panel is crucial for performance.
+
+* **Reduce Path Points** - reduces number of commands in the operation, so the resulting gcode is shorter and can run smoother on the machine
+  * **Threshold (um)** - points with smaller distance (in micrometers) to the path direction will be reduced
+* **Exact mode** - exact mode is related to the strategies that are fully 3d - parallel, cross, block, spiral, circles, waterline, outline fill, carve. It's a very important setting.
+  * **Non exact mode:** In non-exact mode, an image is used to estimate the cutter offsets, and the Sampling raster detail is used to estimate the resolution of the image. Non exact mode is good for high poly meshes, several millions of polygons shouldn't be problem for it, but the sampling raster detail setting is crucial then. Memory overflow can happen if you use e.g. default blender cube that you have by startup, since the cube is 2 meter in size in blender units. For artistic use with high poly meshes, non exact mode is good for most of the cases.
+  * **Exact mode:** a real collision simulation is used, so the collisions are exact. But the speed goes down with increasing number of polygons. It is recommended in these situations: Your model is too big for the non exact mode, you need high precision, your model doesn't have too many faces.
+* **Sampling raster detail** - this parameter is crucial for memory use and mainly speed of blender CAM. In non-exact mode, blenderCAM uses an image to compute the cutter offset positions. If the raster detail is 0.1mm, then a 10x10 cm object will use a 1000x1000 image. If the object size would be 1m, the image would be 10000 x 10000 pixels, which will probably fill the memory of your computer. Check your object size before computing operations.
+* **Simulation sampling raster detail** - same as sampling raster detail, but only for simulation
+* **Detail of circles used for curve offsets** - exactly what it says
+* **Use OpenCAMLib** - use external library for calculating toolpaths, improving toolpath quality (especially with waterlines) and calculation time. Has to be used with exact mode. [[Using-BlenderCAM-with-OpenCAMLib]]
+
+
+### [ Operation Area ]
+![CAM Operation Area](_static/OperationArea.png)
+
+* **Layers** - sets up layers for roughing.
+  * **Layer Height** - specifies thickness of the layers for roughing
+* **Ambient** - how much space surrounding the object will be used for the milling
+  * **All** - a rectangular area will be used
+  * **Around** - object silhouette will be used, with a radius specified by Ambient radius
+* **Depth from object** - takes object depth and sets up the total depth of the operation from it. Otherwise, you can use Operation depth to do the same manually.
+
+
+### [ Material ]
+![CAM material size and position](_static/MaterialPanel.png)
+
+* **Size from Model** - will assume the workpiece/material has the same size as the model, with radius around the model.
+If not enabled then the Material origin and Material size are used in case when the material/workpiece is not the same as the model.  The 3D view will show the machine work area with a hashed outline and the material size and position will be a lighter grey.  The material object is not selectable in the 3D view but can be selected in the Outliner and has the name CAM_material.
+* **Position Object** - this will move the object to positive X and Y and negative Z so that it is fully in the work area and closest to the origin.
+
+
+### [ Movement ]
+![CAM Movement](_static/MovementPanel.png)
+
+* **G64 Trajectory** This enables the "naive cam detector" and enables blending with a tolerance. If you program G64 P0.05, you tell the planner that you want continuous feed, but at programmed corners you want it to slow down enough so that the tool path can stay within 0.05 user units of the programmed path. The exact amount of slowdown depends on the geometry of the programmed corner and the machine constraints, but the only thing the programmer needs to worry about is the tolerance. This gives the programmer complete control over the path following compromise. 
+* **Milling Type** - is supported only for some of the strategies, sets up how the cutter moves into the material
+  * **Meander/ZigZag** - sometimes also called ZigZag , this means you don't care which direction the cutter goes into the material.
+  * **Climb/Down Milling** - the default movement, and mostly used when doing CNC machining if the machine has no or very little backlash. The cutter rotates with the direction of the feed. It can produce a better finish, less stress on the bit, and less power required. If the machine has backlash then Conventional milling is a better choice.
+  * **Conventional/Up Milling** - The cutter rotates against the direction of the feed.  If the machine has backlash that can not be compensated for then this is the better choice.  Some woods cut better with this method but grain direction also has to be considered.
+* **Cutter Spin** - this parameter is not exported, but it is used when setting up the movement type, because with the spindle rotating CCW, all operations go in opposite direction.
+* **Free movement height** - how high will the cutter travel when moving between toolpaths.  Keep it as low as possible to reduce total cutting time.  The Z axis usually has the slowest rapid rates compared to the other two axis X and Y.
+* **First down** - for cutout strategy. If on, the paths are cut one by one to the full depth(all layers), otherwise first all the silhouettes are cut on layer 1, then 2....
+* **Ramp contour** - for cutout strategy, instead of going layer by layer, it goes down all the way on a ramp.
+* **Ramp out** - also going out is performed on a ramp, to prevent burning of the finished piece by staying on one place in XY axes.
+* **Stay Low if possible** - tries to not lift the cutter when going from 1 path to other, when the paths are closer to each other than the cutter radius, which means no extra material will be cut during this travel move.
+* **Protect vertical** - when the angle of the path is above verticality limit, the move will be made vertical. this way vertical surfaces won't get a slope because of the distance between the path points.
+
+
+### [ Feedrate ]
+![CAM feedrate](_static/FeedratePanel.png)
+
+* **Feedrate (/min)** - How much will the machine travel in 1 minute
+* **Spindle (RPM)** - spindle revolutions per minute
+* **Plunge speed** - the feed speed gets reduced when the slope of the path is above the Plunge angle
+* **Plunge angle** - any angle greater than the plunge angle will activate plunge speed
+
+### [ Cutter ]
+![CAM cutter](_static/CutterPanel.png)
+
+* **Type** - supported types are listed in the table below
+* **Diameter** - The exact diameter of the cutting tool.  This is used for calculating tool paths.  For a v-bit its the maximum diameter of the bit.
+* **Flutes** - this parameter is used only for chipload computation.
+* **Tool Number** - this parameter is exported with toolchange command
+* **Description** - A description of the tool.  Currently this is not used for anything.
+* **Cutter object** - a 3D object of your choice available in the drop down list.
+
+| Cutter Types  |   |   |
+|----------|---|---|
+| End      | ![End](_static/cut-end.jpg)  |   |
+| Ballnose | ![Ballnose](_static/cut-ballnose.jpg)  |   |
+| Bullnose | ![Bullnose](_static/cut-bullnose.jpg)  |   |
+| V-Carve  |  ![v-carve](_static/cut-v-carve.jpg) |   |
+| Ballcone |  ![Ballcone](_static/cut-ballcone.jpg) |   |
+| Laser    |  ![Laser](_static/cut-laser.jpg) |   |
+| Custom   |  ![Custom](_static/cut-custom.jpg) |   |
+
+
+### [ Chains ]
+![New chain](_static/ChainsPanel.png)
+
+This enables you to chain operations. It is useful for simulating more operations or exporting a chain of operations if you have automatic toolchanger or use the same tool for several operations.

scripts/addons/docs/panels.md

@@ -1,229 +0,0 @@
-# Panels
-
-
-## Enter CAM mode
-All of the CAM panels are found in the Render Data settings.
-
-To put blender into CAM mode do the following. The Blendercam add-on must be enabled already. 
-
-First of all, change render engine to CAM to use the blender cam tool.
-
-![Renderer selection](_static/cam_render.png)
- 1. select **Blender CAM** as the render engine  
- 2. select the **Properties** editor
- 3. select the **Render** data in order to see the CAM panels
-
-
-## CAM operations Panel
-![CAM operations](_static/opPanel2.png)
-* **Calculate path** - This calculates the operation which is currently selected in the cam operations list. The Button will stay selected until the calculation is completed.
-
-* **Simulate operation** - Works for 3 axis operations, but not for all. It creates a new object which shows the simulation - the subdivision of the object can be increased, and the resolution of the simulation also depends on simulation sampling raster detail, which is in the optimization panel
-
-* **Operation name** - Select this field to change the name of the currently selected operation.
-
-* **File name** - Name of the gcode file. The file extension used will be determined by the g-code post processor selected. See [Cam Machine panel](Blendercam-Panel-Descriptions.md) for setting post processor.
-
-* **Source of data** - This can be either 1 object, a group of objects, or an image.
-
-  * **Object** - a Blender object.  This could be a mesh, or a curve.
-
-  * **Group** - Objects in a group.  Select all objects you want to use, and hit Ctrl+G to create a new group. Then type name of the group in the field (Group will be the name of the first group you create).
-
-  * **Image** - Open an image that will be used as a height/depth map.
-
-* **Object** - the blender object that will be used in the CAM operation. Select the object from a drop down list. Write it's name in the field, it should auto-complete and give a list of objects to select from.
-**NOTE:** if you change the objects name later on then you must also change it here.  The field will turn red if the object can not be found.
-
-
-## CAM info and Warnings Panel
-![Cam Info & warnings](_static/camInfo.png)
-
-This panel will show any trouble found during the computation, estimated operation time, and chipload data
-
-
-## CAM operation setup Panel
-* ![Strategy](_static/opList.png)
-
-
-**Strategy** sets one of the strategies.
-
-
-
-  * **Parallel** 
-
-      ![Parallel](_static/opParallel.png)  
-
-      Parallel paths at any angle
-
-  * **Pocket**
-
-    ![pocket](_static/opPocket.png)  
-
-  * **Cutout**
-
-    ![profile cutout](_static/opProfile.png)  
-
-    Cutout a silhouette using optional offset.
-
-  * **Drill**
-
-    ![drill](_static/opDrill.png)  
-
-    This detects circles or squares in any 2d curve and converts these into a drill operation.  Supports peck drilling if layers are enabled.
-
-  * **Cross**
-
-    ![cross](_static/opCross.png)  
-
-  * **Block**
-
-    ![block](_static/opBlock.png)  
-
-  * **Spiral**
-
-    ![spiral](_static/opSpiral.png)  
-
-    Best suited for coins or other circular objects
-
-  * **Circles**
-
-    ![circles](_static/opCircle.png)  
-
-    Best suited for coins or other circular objects
-
-  * **Outline Fill**
-
-    ![outline fill](_static/opOutline.png)  
-
-  * **Carve**
-
-    ![carve](https://cloud.githubusercontent.com/assets/648108/12060353/19527cf6-af44-11e5-9de1-27cf1c98a90a.jpg) 
-
-    Projects any 2d curve on 3d surface
-
-  * **Overview of principles strategies**
-
-  ![Strategy Overview](_static/opOverview.png)
-  
-  ![waterline](https://cloud.githubusercontent.com/assets/648108/12060351/1316d53a-af44-11e5-8158-31c349a7a265.jpg)
-
-Various strategies will combine these parameters:
-  * **distance between toolpaths** - also called stepover in other applications
-  * **distance along toolpaths** - how dense will be the operation path. This can influence accuracy of the machining.
-  * **angle of paths** - this rotates the parallel and cross strategies by the specified amount. Note that e.g. rotating by 90 changes the basic axis from X to Y
-  * **parallel step back** - this function is only for finishing pass, where you still have to cut some substantial amount of material, and want also to save the cutter. If you set up to climb movement, it goes with climb into material, then goes in the other direction one step back - this uses the back movement of the machine for finishing the surface. Note that this also means the cutting into material will happen with a rate which is 2x of distance between toolpaths If you don't know what this all means, don't use this function.
-  * **Skin** - useful for roughing, leaves a layer on the surface for finishing
-  * **Inverse milling** - used if you want to mill a form directly from positive of the object. Does not work in exact mode. Only works for 3 axis strategies.
-  * **Direction** - for block and spiral strategy, decides if the path progresses from inside or from outside
-  * **Carve depth** - decides how deep below the surface will go the carve operation
-  * **Don't merge outlines when cutting** - for cutout strategy. Does not merge outlines - this results into cutting in the object area! It is usefully when milling PCBs, where you don't need exact shape but need to separate areas with engraving.
-  * **Use bridges** - for cutout operation, places automatically bridges by the rules set by options that will appear after this is enabled: width, height, minimum per curve, distance.
-
-
-## CAM optimization Panel
-![Cam Optimization](_static/camOptim.png)
-
-This panel is crucial for performance of blenderCAM.
-
-* **Reduce path points** - reduces number of commands in the operation, so the resulting gcode is shorter and can run smoother on the machine
-  * **Reduction threshold in um** - points with smaller distance (in micrometers) to the path direction will be reduced
-* **Use exact mode** - exact mode is related to the strategies that are fully 3d - parallel, cross, block, spiral, circles, waterline, outline fill, carve. It's a very important setting.
-  * **Non exact mode:** In non-exact mode, an image is used to estimate the cutter offsets, and the Sampling raster detail is used to estimate the resolution of the image. Non exact mode is good for high poly meshes, several millions of polygons shouldn't be problem for it, but the sampling raster detail setting is crucial then. Memory overflow can happen if you use e.g. default blender cube that you have by startup, since the cube is 2 meter in size in blender units. For artistic use with high poly meshes, non exact mode is good for most of the cases.
-  * **Exact mode:** a real collision simulation is used, so the collisions are exact. But the speed goes down with increasing number of polygons. It is recommended in these situations: Your model is too big for the non exact mode, you need high precision, your model doesn't have too many faces.
-* **Sampling raster detail** - this parameter is crucial for memory use and mainly speed of blender CAM. In non-exact mode, blenderCAM uses an image to compute the cutter offset positions. If the raster detail is 0.1mm, then a 10x10 cm object will use a 1000x1000 image. If the object size would be 1m, the image would be 10000 x 10000 pixels, which will probably fill the memory of your computer. Check your object size before computing operations.
-* **Simulation sampling raster detail** - same as sampling raster detail, but only for simulation
-* **Detail of circles used for curve offsets** - exactly what it says
-* **Use OpenCAMLib** - use external library for calculating toolpaths, improving toolpath quality (especially with waterlines) and calculation time. Has to be used with exact mode. [[Using-BlenderCAM-with-OpenCAMLib]]
-
-
-## CAM operation area panel
-![CAM Operation Area](_static/camOpArea.png)
-* **Use layers** - sets up layers for roughing.
-* **Step down** - specifies thickness of the layers for roughing
-* **Ambient** - how much space surrounding the object will be used for the milling
-  * **all** - a rectangular area will be used
-  * **around** - object silhouette will be used, with a radius specified by Ambient radius
-* **Depth from object** - takes object depth and sets up the total depth of the operation from it. Otherwise, you can use Operation depth to do the same manually.
-
-
-## CAM material size and position panel
-![CAM material size and position](_static/materialSize.png)
-
-* **Estimate from model** - will assume the workpiece/material has the same size as the model, with radius around the model.
-If not enabled then the Material origin and Material size are used in case when the material/workpiece is not the same as the model.  The 3D view will show the machine work area with a hashed outline and the material size and position will be a lighter grey.  The material object is not selectable in the 3D view but can be selected in the Outliner and has the name CAM_material.
-* **Position object** - this will move the object to positive X and Y and negative Z so that it is fully in the work area and closest to the origin.
-
-
-## CAM movement panel
-![CAM Movement](_static/camMovement.png)
-
-* **G64 trajectory** This enables the "naive cam detector" and enables blending with a tolerance. If you program G64 P0.05, you tell the planner that you want continuous feed, but at programmed corners you want it to slow down enough so that the tool path can stay within 0.05 user units of the programmed path. The exact amount of slowdown depends on the geometry of the programmed corner and the machine constraints, but the only thing the programmer needs to worry about is the tolerance. This gives the programmer complete control over the path following compromise. 
-* **Movement type** - is supported only for some of the strategies, sets up how the cutter moves into the material
-  * **Meander/ZigZag** - sometimes also called ZigZag , this means you don't care which direction the cutter goes into the material.
-  * **Climb/Down Milling** - the default movement, and mostly used when doing CNC machining if the machine has no or very little backlash. The cutter rotates with the direction of the feed. It can produce a better finish, less stress on the bit, and less power required. If the machine has backlash then Conventional milling is a better choice.
-  * **Conventional/Up milling** - The cutter rotates against the direction of the feed.  If the machine has backlash that can not be compensated for then this is the better choice.  Some woods cut better with this method but grain direction also has to be considered.
-* **Spindle rotation** - this parameter is not exported, but it is used when setting up the movement type, because with the spindle rotating CCW, all operations go in opposite direction.
-* **Free movement height** - how high will the cutter travel when moving between toolpaths.  Keep it as low as possible to reduce total cutting time.  The Z axis usually has the slowest rapid rates compared to the other two axis X and Y.
-* **First down** - for cutout strategy. If on, the paths are cut one by one to the full depth(all layers), otherwise first all the silhouettes are cut on layer 1, then 2....
-* **Ramp contour** - for cutout strategy, instead of going layer by layer, it goes down all the way on a ramp.
-* **Ramp out** - also going out is performed on a ramp, to prevent burning of the finished piece by staying on one place in XY axes.
-* **Stay low if possible** - tries to not lift the cutter when going from 1 path to other, when the paths are closer to each other than the cutter radius, which means no extra material will be cut during this travel move.
-* **Protect vertical** - when the angle of the path is above verticality limit, the move will be made vertical. this way vertical surfaces won't get a slope because of the distance between the path points.
-
-
-## CAM feedrate panel
-![CAM feedrate](_static/camFeedrate.png)
-
-* **feedrate/minute** - How much will the machine travel in 1 minute
-* **Plunge speed** - the feed speed gets reduced when the slope of the path is above the Plunge angle
-* **Plunge angle** - any angle greater than the plunge angle will activate plunge speed
-* **Spindle rpm** - spindle revolutions per minute
-
-
-## CAM cutter panel
-![CAM cutter](_static/camCut.png)
-
-* **Tool number** - this parameter is exported with toolchange command
-* **Cutters** - supported types are now following:
-
-![CAM cutters](_static/camCut2.png)
-
-
-
-| Cutters  |   |   |
-|----------|---|---|
-| End      | ![End](_static/cut-end.jpg)  |   |
-| Ballnose | ![Ballnose](_static/cut-ballnose.jpg)  |   |
-| Bullnose | ![Bullnose](_static/cut-bullnose.jpg)  |   |
-| V-Carve  |  ![v-carve](_static/cut-v-carve.jpg) |   |
-| Ballcone |  ![Ballcone](_static/cut-ballcone.jpg) |   |
-| Laser    |  ![Laser](_static/cut-laser.jpg) |   |
-| Custom   |  ![Custom](_static/cut-custom.jpg) |   |
-
-  ![custom cutter](_static/cutCustom.png)
-
-  * Cutter object - a 3D object of your choice available in the drop down list.
-
-* **Cutter diameter** - The exact diameter of the cutting tool.  This is used for calculating tool paths.  For a v-bit its the maximum diameter of the bit.
-* **Cutter flutes** - this parameter is used only for chipload computation.
-* **Tool description** - A description of the tool.  Currently this is not used for anything.
-
-
-## CAM machine panel
-![Cam machine](_static/machine.png)
-
-This panel sets up your machine and the settings are common in the whole file.
-You can also set up your machine and then save your default file with Ctrl+U command. This way you will always start with the settings you need.
-
-* **Post processor** - this defines the formatting of the output file. If your machine is not in the list, you can try the Iso code, which is standardized g-code
-
-![post processor](_static/processor.png)
-
-* **Unit system** - Metric or Imperial
-* **Work area** - if the operation has a larger area than this, you will get a warning in the info panel
-* **Feedrate minimum/maximum** - this will limit your feed speeds set up in the feedrate panel.
-
-
-## CAM chains panel
-This enables you to chain operations. It is useful for simulating more operations or exporting a chain of operations if you have automatic toolchanger or use the same tool for several operations.

scripts/addons/docs/starting.md

@@ -1,89 +1,156 @@
 # Getting Started
 
-This is a step-by-step tutorial on generating a toolpath with Blender CAM. For detailed description of panel options go [here](panels.md).
+This is a step-by-step tutorial on generating your first toolpath with Fabex.
 
-## Change render engine
-First of all, change render engine to CAM to use the blender cam tool.
+For detailed descriptions of Panel options go [here](interface.md).
 
-![Renderer selection](_static/cam_render.png)
+## Setup your Scene
+You can use any object to generate toolpaths, but for the purpose of this guide we will use Suzanne, the monkey.
 
+To reproduce the results shown below you will need to:
+- select and delete the default cube
+- click **Add** > **Mesh** > **Monkey** _(or press Shift+A to get the Add Menu and do the same)_
 
-## Change units in Blender
+Now we are going to scale and rotate the monkey head so that it gives us the best results and doesn't trigger any warnings about being too big for our machine:
+- press **S**, then **.05** on your keyboard to scale it down
+- press **R**, then **X**, then **-90** to rotate it on the X axis by -90 degrees
+- press **S**, then **Z**, then **.5** to scale it down on the Z axis
 
-Change units to metric or imperial in Scene properties.
-![Renderer selection](_static/milim.png):
+> [!NOTE]
+> _If you don't feel the need to reproduce the guide results exactly, you can skip all of the above and perform the operations on the default cube, but you will get a warning about the object being too big for your machine if you don't scale it down to fit inside the **CAM_machine** area._
 
+## Change the Render Engine
+In the **Properties** area, in the **Render** tab, set the **Render Engine** to **Fabex CNC/CAM**
 
-## Setup machine parameters
+![Renderer selection](_static/RenderEngine.png)
 
-Setup machine parameters (postprocessor, maximum feed rate, work area, etc.) in 'CAM Machine' options.
+## Setup your Machine Parameters
 
-![Machine setup](_static/setup_machine.png)
+In the **[ Machine ]** panel, enter the specs of your CNC Machine, including:
+- **Post-Processor**
+- **Unit System** *(Metric or Imperial)* & **Length Unit** *(ft, in, m, mm)*
+- **Work Area**
+- **Feedrate** & **Spindle Speed** Min/Max
+- **Machine G-code** output options
+- Custom **Position Definitions** for Start, End and Tool Change 
+- Multi-Axis Options and more
 
-## Add a new operation
+![Machine setup](_static/MachineParameters.png)
 
-Add new operation in the render properties.
-![New operation](_static/newop.png)
+## Add an Operation
 
-Choose Parallel (or Outline Fill, Circles, Spiral, Block, Cross) in the Strategy dialog. Waterline option works best when OpenCAMLib is installed and other operations require curve data source. See how to generate curves from mesh model [here](Profile%20and%20Pocket%20operations.md).
+In the **[ Operations ]** panel, click the **+** button to add a new Operation.
 
-![Select operation](_static/selectOperation.png)
+![New operation](_static/NewOperation.png)
 
-In Object dialog select object being source of geometry for toolpath generation.
+_Once an Operation has been added, the rest of the Interface will populate with Operation settings panels._
 
-## Configure Cam Material and position object
+## Choose a Milling Strategy
 
-In CAM Material size and position, set radius around model option to reflect the amount of stock material to be machined.
+In the  **[ Operation Setup ]** panel, choose **Parallel** from the **Strategy** dropdown. 
 
-![Before position](_static/beforePosition.png)
+![Select operation](_static/ChooseStrategy.png)
 
-Manually position object inside work area, or use "Position object" option to position it automatically.
+**Outline Fill**, **Circles**, **Spiral**, **Block**, or **Cross** will also work for this example. 
 
-![Click position](_static/positionObject.png)
+**Waterline** and other operations require curve data source. See how to generate curves from mesh model [here](Profile%20and%20Pocket%20operations.md).
 
-![After position](_static/afterPosition.png)
+> [!NOTE]
+> _If you are not sure what each milling strategy does, check the Strategy page for pictures and explanations of how each works._
 
-If the box representing material doesn't update, uncheck "Estimate from model" option and then check it again.
+## Setup Stock Material and Position your Object
 
-## Configuration of the active Operation
+In the **[ Material ]** panel, click **Size from Model** to allow Fabex to auto-calculate the size of the required Stock Material, you can then set **Additional Radius** to mill additional stock around object. 
 
-Set "Distance between toolpaths" to desired value.
+If you know the dimensions of your stock, e.g. a plywood sheet, you can uncheck **Size from Model** and enter the dimensions manually.
 
-"Distance along toolpaths" option determines accuracy. Lower values result in more accurate toolpath, but make computation slower and increase amount of resulting G-code.
+You can manually position object inside the Machine's Work Area, or use **Position Object** to position it automatically using the listed alignment options.
 
-Select "Use exact mode" - it improves accuracy. If you have [OpenCAMLib](Opencamlib%20Installation.md) installed, also select "UseOpenCAMLib" - it impoves accuracy and speeds up the computing time. OpenCAMLib also enables high quality algorithm from calculating waterline toolpaths.
+![Material Panel](_static/MaterialPanel.png)
 
-CAM Movement:
+> [!NOTE]
+> _If the box representing material doesn't update, uncheck **Size from Model** and then check it again._
 
-Enter layer depth (in Step Down dialog), operation depth, start depth and optionally end depth (if "Depth from object" is disabled).
+## Configure the Operation Settings
+### [ Operation Setup ]
+In the **[ Operation Setup ]** panel, under the **Parallel** settings, find **Toolpath Distance**.
 
-CAM Feedrate:
+**Between** is the distance between toolpaths, and allows you to set Stepover values to determine how close each path should be to the next.
 
-Set feedrate and spindle rpm. "Plunge speed" and "Plunge angle" allows slowing down feedrate when the cutter is moving down on steep areas.
+**Along** determines path accuracy. Paths are made up of points, and the lower the distance between them, the more points you will have. 
 
-Cam Cutter:
+Lower values result in more accurate toolpath, but make computation slower and increase amount of resulting G-code.
 
-Set cutter tool number (used in G-code), type, number of flutes and diameter.
+![Toolpath Distance](_static/ToolpathDistance.png)
 
-## Multiples operations in a chain
+### [ Optimisation ]
+Click to enable **Exact Mode** - it improves accuracy. 
 
-To join multiple operations into a single G-code file, use CAM chains dialog.
+You can also select **Use OpenCAMLib** - it improves accuracy and speeds up the computing time. 
 
-![New chain](_static/newChain.png)
+![](_static/OptimisationPanel.png)
 
-## Calculate Path and Generate Gcode file
+*OpenCAMLib also enables a high quality algorithm to calculate waterline toolpaths.*
 
-Click "Calculate Path" to generate toolpath. If "Auto export" option is selected, G-code file will also be created.
+### [ Operation Area ]
 
-![Calculate path](_static/calculatePath.png)
+In the **[ Operation Area ]** panel, click the arrow next to **Layers** to enter a **Layer Height**.
 
-![Calculate path view](_static/calculatePath2.png)
+Under **Operation Depth** you can set the **Start** and **Max** depth. 
 
-## Quick look of the final result
+![](_static/OperationArea.png)
 
-Next click "Simulate operation" to create model representing machined material.
+_**Max** depth is set to auto-calculate from the selected **Object** by default._
 
-![Simulate Operation](_static/simulateOp.png)
+### [ Feedrate ]
 
+Set the **Feedrate** _(in units per minute)_ and **Spindle** speed _(in revolutions per minute)_ for the Operation. 
 
+![](_static/FeedratePanel.png)
+
+***Plunge** **Speed** and **Angle** allows slows down the operation feedrate when the cutter is moving down on steep areas.*
+
+### [ Cutter ]
+
+Specify your Cutter **Type**, number of **Flutes** and **Diameter.**
+
+![](_static/CutterPanel.png)
+
+*Set the **Tool Number** and **Description** if applicable.*
+
+## Calculate Path and Generate Gcode
+
+Back in the **[ Operations ]** panel, click **Calculate Path & Export Gcode**.
+
+![Calculate path](_static/OperationsPanelSuzanne.png)
+
+This will calculate the toolpath, add it to the Blender scene and export a Gcode file to the same directory as your .blend file.
+
+![Calculate path view](_static/SuzannePath.png)
+
+## Operation Simulation
+
+Click **Simulate This Operation** to create model representing your machined material. 
+
+You can use this to determine your best milling strategy, how much finishing work a job will need, etc.
+
+![Simulate Operation](_static/SuzanneSimulation.png)
+
+Or, combine it with Blender shaders and HDRIs to get a better idea of what your piece will look like in your chosen material, with light and shadow.
+
+![Simulate Operation](_static/SuzanneWoodSim.png)
+
+## Combine Multiple Operations in a Chain
+
+You may need to combine multiple strategies and Opertations to achieve your desired result, and chains make that possible.
+
+Chains allow you to combine multiple Operations for Gcode export or Simulation.
+
+In the **[ Chains ]** panel, click the **+** button to add a new Chain.
+
+This will add a second box below the first to hold the Operations for this Chain.
+
+Click the lower **+** button to add the active Operation to your Chain.
+
+![New chain](_static/ChainsPanel.png)
 

scripts/addons/docs/strategies.md

@@ -0,0 +1,59 @@
+# Strategies
+
+  * **Parallel** 
+
+      ![Parallel](_static/opParallel.png)  
+
+      Parallel paths at any angle
+
+  * **Pocket**
+
+    ![pocket](_static/opPocket.png)  
+
+  * **Cutout**
+
+    ![profile cutout](_static/opProfile.png)  
+
+    Cutout a silhouette using optional offset.
+
+  * **Drill**
+
+    ![drill](_static/opDrill.png)  
+
+    This detects circles or squares in any 2d curve and converts these into a drill operation.  Supports peck drilling if layers are enabled.
+
+  * **Cross**
+
+    ![cross](_static/opCross.png)  
+
+  * **Block**
+
+    ![block](_static/opBlock.png)  
+
+  * **Spiral**
+
+    ![spiral](_static/opSpiral.png)  
+
+    Best suited for coins or other circular objects
+
+  * **Circles**
+
+    ![circles](_static/opCircle.png)  
+
+    Best suited for coins or other circular objects
+
+  * **Outline Fill**
+
+    ![outline fill](_static/opOutline.png)  
+
+  * **Carve**
+
+    ![carve](https://cloud.githubusercontent.com/assets/648108/12060353/19527cf6-af44-11e5-9de1-27cf1c98a90a.jpg) 
+
+    Projects any 2d curve on 3d surface
+
+  * **Overview of principles strategies**
+
+  ![Strategy Overview](_static/opOverview.png)
+  
+  ![waterline](https://cloud.githubusercontent.com/assets/648108/12060351/1316d53a-af44-11e5-8158-31c349a7a265.jpg)

scripts/addons/docs/users.rst

@@ -0,0 +1,23 @@
+User Guide
+*****************
+
+.. toctree::
+   :maxdepth: 1
+
+   install
+   starting
+   interface
+   tools
+   profilepocket
+
+This section is for new users, containing basic info on how to install and use the extension.
+
+:doc:`install` contains instructions for downloading and installing Fabex and Blender.
+
+:doc:`starting` is a good place for newcomers to begin.
+
+:doc:`panels` gives descriptions of what each of the panels in the UI is for.
+
+:doc:`tools` offers an introduction to the various tools packaged with Fabex.
+
+:doc:`profilepocket` contains a step-by-step guide for completing these common operations.