Pharo-FreeCAD utility
# StFreeCAD
A package to create and edit parametric 3D models in FreeCAD from Pharo. This project is a part of GSoC 2021 https://summerofcode.withgoogle.com/dashboard/project/4824667119943680/overview/.
- FreeCAD is an Open Source 3D Parametric modeller written in C++ and Python, and has powerful CAD scripting abilities via its Python interpreter.
- StFreeCAD uses sockets to communicate with FreeCAD python interpreter. Commands are sent to it in the form of python strings generated using Python3Generator: https://github.com/juliendelplanque/Python3Generator.
- To know more about CAD scripting in FreeCAD, follow the link: https://wiki.freecadweb.org/FreeCAD_Scripting_Basics.
- FreeCAD wiki for Powerhub users https://wiki.freecadweb.org/Power_users_hub is a good place to understand the way 3D/2D objects are handled in FreeCAD.
## Features currently implemented/not implemented
- [x] Basic Part creation (Box, Cylinder)
- [x] Changing placement of created objects in FreeCAD
- [x] Querying the properties of objects created in FreeCAD
- [ ] Storing FreeCAD Part objects in Pharo
- [ ] Mimicing FreeCAD class hierarchy in Pharo
## Installation
To run the package, you need to have FreeCAD installed on your computer. If not installed, download and install via the link: https://www.freecadweb.org/downloads.php.
### FreeCAD side
Once FreeCAD is installed, you need to install the external workbench given in this repository to your FreeCAD. To proceed, download the repository and extract the folder named **StFreeCADSide** on your local hard disk.
Further instructions vary for different Operating Systems. The following link describes the installation https://wiki.freecadweb.org/How_to_install_additional_workbenches. Follow *Manual Installation* steps for your appropriate OS.
#### For Windows:
- Within FreeCAD, locate the macro path by choosing Edit → Preferences → General → Macro and look for the ”Macro path”
- The default macro path is usually in *C:\Users\username\Appdata\Roaming\FreeCAD*.
- Within the macro-directory create (if not already present) a folder called **Mod**.
- Within the **Mod** folder, place the **StFreeCADSide** folder extracted from the repository.
### Pharo side
To install this project in your Pharo image, open a playground and *DoIt* the following code snippet:
```
Metacello new
baseline: 'StFreeCAD';
repository: 'github://roymrinalkanti/StFreeCAD:main/src';
load
```
## How to begin using StFreeCAD
1. Load the image with the package installed.
2. Start FreeCAD and wait for the welcome page to load.
3. On Pharo, run the following code to establish connection with FreeCAD.
```
client := ClientFreeCAD new.
```
4. To cease communication between Pharo and FreeCAD, pass the message *stop* to the *ClientFreeCAD* object:
```
client stop.
```
## Commands
StFreeCAD has methods to send Python commands to the running FreeCAD's python interpreter. It can also send Python commands generated by Python3Generator. Furthermore, it has a few methods to accomplish basic 3D part-scripting.
Below are the basic methods used to command FreeCAD.
```
ClientFreeCAD>>sendDataAndListen: aString
```
executes *aString* in FreeCAD's python interpreter, and returns its error status.
```
ClientFreeCAD>>retrieveValue: aString
```
executes *aString* in FreeCAD's python interpreter, and returns its value as a bytestring.
```
ClientFreeCAD>>evaluate: aP3Generable
```
executes *aP3Generable* instructions.
```
ClientFreeCAD>>return: aP3Generable
```
Returns the value of *aP3Generable* command.
More methods are explained briefly in the example below.
## Example
```
"Before connecting make sure that FreeCAD is running. You can start FreeCAD by double-clicking the FreeCAD shortcut.
Alternatively, you can start FreeCAD by noting down the FreeCAD.exe location and running the following command:"
'D:\FreeCAD 0.19\bin\FreeCAD.exe' startProgram.
"Replace the string to the location of FreeCAD.exe in your computer"
client := ClientFreeCAD new.
"Establishes communication between FreeCAD and Pharo"
client newDocument; activateWorkbench: #Part.
"Creates a new Document; activates the Part-Workbench (used to create 3D objects)"
box := client makeBoxL: 12 W: 13 H: 14.
"creates a box with user-provided length-width-height values"
box2 := client makeBox.
"creates a box with default dimensions"
cone := client makeCone.
cone2 := client makeConeR1: 10 R2: 20 H: 10 A: 270.
"Creates a cone with radius1-radius2-height-angle values provided by user"
position:=FreeCAD vectorX: 3 Y: 4 Z: 5.
"Creates a Vector with x-y-z values. Used to define position of an object, and change it"
client position: position object: box.
"Positions the object provided (*box*) to the given position vector (*position*)"
rotation := FreeCAD rotationAxis: position angle: 45.
"Defines a rotation along an axis vector by an angle."
client rotate: rotation object: cone.
"rotates an object as defined by rotation"
"Boolean operations on 2 objects"
cut:=client differenceOn: box and: cone.
common:=client intersectionOn: box and: cone.
section:=client sectionOn: box and: cone.
fuse:=client unionOn: box and: cone.
allObjs :=client getAllObjects .
"returns a list of objects in FreeCAD"
client return: (box=>#Shape=>#Vertex1=>#X).
"Accessing the value of 'box.Shape.Vertex1.X'"
client saveAsDocument: 'D:/test2.FCStd'.
"saveAs to given directory"
client saveDocument
"saves document"
client openDocument: 'D:/test.FCStd'.
"opens document at given directory"
client stop.
```
## Troubleshooting
- If a socket connection error arises while running StFreeCAD, certain functions that involve returning information from FreeCAD might give an *Receieve Timeout* error.
In such a case, execute *close* message like so:
```
client close.
```
Then open the Process Browser in Pharo (On Pharo 8, it is in System -> Process Browser). Tereminate any socket-related processes. They are usually preceeded by numbers.
Now restart FreeCAD, and connect to it by executing the following command:
```
client := ClientFreeCAD new.
```
## Known Bugs and Issues
- Socket communication is not established sometimes between FreeCAD and Pharo. See **Troubleshooting** for more details.
- Older methods (marked with 'Deprecated' protocol) do not return expected returns.
- **StFreeCAD-Objects** is a package that is not implemented yet. It will be implemented in further revisions of package.