OpenSCAD Workbench: Difference between revisions

From FreeCAD Documentation
(Section for dependencies)
mNo edit summary
(42 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<languages/>
<languages/>
<translate>
<translate>

<!--T:21-->
<!--T:21-->
{{Docnav
{{docnav|[[Mesh Module|Mesh Module]]|[[Part Module|Part Module]]|IconL=Workbench_Mesh.svg|IconR=Workbench_Part.svg}}
|[[Mesh_Workbench|Mesh Workbench]]
|[[Part_Workbench|Part Workbench]]
|IconL=Workbench_Mesh.svg
|IconR=Workbench_Part.svg
}}


<!--T:30-->
</translate>
[[Image:OpenSCADWorkbench.svg|64px]]
[[Image:Workbench_OpenSCAD.svg|thumb|128px|OpenSCAD workbench icon]]
<translate>


== Introduction == <!--T:1-->
== Introduction == <!--T:1-->


<!--T:23-->
The OpenSCAD Workbench is intended to offer interoperability with the open source software [http://www.openscad.org/ OpenSCAD]. This program is not distributed as part of FreeCAD, but should be installed to make full use of this workbench.
The [[Image:Workbench_OpenSCAD.svg|24px]] [[OpenSCAD_Workbench|OpenSCAD Workbench]] is intended to offer interoperability with the open source software [http://www.openscad.org/ OpenSCAD]. This program is not distributed as part of FreeCAD, but should be installed to make full use of this workbench. OpenSCAD should not be confused with [[OpenCASCADE|OpenCASCADE]], which is the geometrical kernel that FreeCAD uses to build geometry on screen. The OpenCASCADE libraries are always needed to use FreeCAD, while the OpenSCAD executable is entirely optional.


<!--T:4-->
<!--T:4-->
Line 21: Line 27:
{{TOCright}}
{{TOCright}}
[[Image:OpenSCADexamaple1.png]]
[[Image:OpenSCADexamaple1.png]]
<translate>

== Dependencies == <!--T:24-->

<!--T:25-->
In FreeCAD 0.19, the Ply (Python-Lex-Yacc) module, which is used to import CSG files, was removed from the FreeCAD source code, as it is a third party library not developed by FreeCAD. As a result, you now need to install Ply before using the OpenSCAD Workbench. When using a pre-packaged, stable version of FreeCAD this dependency should be installed automatically in all platforms; in other cases, for example, when [[Compiling|compiling]] from source, you may have to install it from an online repository.

<!--T:28-->
In openSUSE this is done by:
</translate>
{{Code|code=
sudo zypper install python3-ply
}}
<translate>

<!--T:26-->
In Debian/Ubuntu based systems this is done like the following:
</translate>
{{Code|code=
sudo apt install python3-ply
}}
<translate>

<!--T:27-->
The general installation in all platforms can be done from the Python package index.
</translate>
{{Code|code=
pip3 install --user ply
}}
<translate>
<translate>


Line 33: Line 68:


<!--T:18-->
<!--T:18-->
* [[Image:OpenSCAD_ColorCodeShape.png|32px]] [[OpenSCAD_ColorCodeShape|Color Code Shape]]: Change the color of selected or all shapes based on their validity.
* [[Image:OpenSCAD_ColorCodeShape.svg|32px]] [[OpenSCAD_ColorCodeShape|Color Code Shape]]: Change the color of selected or all shapes based on their validity.
* [[Image:OpenSCAD_ReplaceObject.png|32px]] [[OpenSCAD_ReplaceObject|Replace Object]]: Replace an object in the feature tree.
* [[Image:OpenSCAD_ReplaceObject.svg|32px]] [[OpenSCAD_ReplaceObject|Replace Object]]: Replace an object in the feature tree.
* [[Image:OpenSCAD_RemoveSubtree.png|32px]] [[OpenSCAD_RemoveSubtree|Remove Subtree]]: Removes the selected objects and all children that are not referenced from other objects.
* [[Image:OpenSCAD_RemoveSubtree.svg|32px]] [[OpenSCAD_RemoveSubtree|Remove Subtree]]: Removes the selected objects and all children that are not referenced from other objects.
* [[Image:OpenSCAD_RefineShapeFeature.png|32px]] [[OpenSCAD_RefineShapeFeature|Refine Shape Feature]]: Create Refine Shape Feature.
* [[Image:OpenSCAD_RefineShapeFeature.svg|32px]] [[OpenSCAD_RefineShapeFeature|Refine Shape Feature]]: Create Refine Shape Feature.
* [[Image:OpenSCAD_IncreaseTolerance.png|32px]] [[OpenSCAD_IncreaseTolerance|Increase Tolerance Feature]]: Increases tolerance of edges/faces/vertex of selected object(s).
* [[Image:OpenSCAD_MirrorMeshFeature.svg|32px]] [[OpenSCAD_MirrorMeshFeature|Mirror Mesh Feature]]: Create Mirror Mesh Feature.
* [[Image:OpenSCAD_ScaleMeshFeature.svg|32px]] [[OpenSCAD_ScaleMeshFeature|Scale Mesh Feature]]: Scale a Mesh Feature.
* [[Image:OpenSCAD_Edgestofaces.png|32px]] [[OpenSCAD_Edgestofaces|Convert Edges To Faces]]: Convert edges to faces. Useful to prepare imported DXF geometry for extrusion.
* [[Image:OpenSCAD_ExpandPlacements.png|32px]] [[OpenSCAD_ExpandPlacements|Expand Placements]]: Expand all placements downwards the FeatureTree.
* [[Image:OpenSCAD_ResizeMeshFeature.svg|32px]] [[OpenSCAD_ResizeMeshFeature|Resize Mesh Feature]]: Resize a Mesh Feature.
* [[Image:OpenSCAD_IncreaseToleranceFeature.svg|32px]] [[OpenSCAD_IncreaseToleranceFeature|Increase Tolerance Feature]]: Increases tolerance of edges/faces/vertex of selected object(s).
* [[Image:OpenSCAD_ExplodeGroup.png|32px]] [[OpenSCAD_ExplodeGroup|Explode Group]]: Explodes fused part primitives.
* [[Image:OpenSCAD_Edgestofaces.svg|32px]] [[OpenSCAD_Edgestofaces|Convert Edges To Faces]]: Convert edges to faces. Useful to prepare imported DXF geometry for extrusion.
* [[Image:OpenSCAD_AddOpenSCADElement.png|32px]] [[OpenSCAD_AddOpenSCADElement|Add OpenSCAD Element]]: Add an OpenSCAD element by entering OpenSCAD code into the task panel.
* [[Image:OpenSCAD_MeshBoolean.png|32px]] [[OpenSCAD_MeshBoolean|Mesh Boolean]]: Creates new mesh object by boolean operation from shapes.
* [[Image:OpenSCAD_ExpandPlacements.svg|32px]] [[OpenSCAD_ExpandPlacements|Expand Placements]]: Expand all placements downwards the FeatureTree.
* [[Image:OpenSCAD_Hull.png|32px]] [[OpenSCAD_Hull|Hull]]: Applies a hull to selected shapes.
* [[Image:OpenSCAD_ExplodeGroup.svg|32px]] [[OpenSCAD_ExplodeGroup|Explode Group]]: Explodes fused part primitives.
* [[Image:OpenSCAD_AddOpenSCADElement.svg|32px]] [[OpenSCAD_AddOpenSCADElement|Add OpenSCAD Element]]: Add an OpenSCAD element by entering OpenSCAD code into the task panel.
* [[Image:OpenSCAD_Minkowski.png|32px]] [[OpenSCAD_Minkowski|Minkowski]]: Applies a minkowski sum to selected shapes.
* [[Image:OpenSCAD_MeshBoolean.svg|32px]] [[OpenSCAD_MeshBoolean|Mesh Boolean]]: Creates new mesh object by boolean operation from shapes.
* [[Image:OpenSCAD_Hull.svg|32px]] [[OpenSCAD_Hull|Hull]]: Applies a hull to selected shapes.
* [[Image:OpenSCAD_Minkowski.svg|32px]] [[OpenSCAD_Minkowski|Minkowski]]: Applies a minkowski sum to selected shapes.


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


<!--T:20-->
<!--T:20-->
* [[Image:Std_DlgParameter.png|32px]] [[OpenSCAD_Preferences|Preferences]]: preferences available for the OpenSCAD tools.
* [[Image:Std_DlgPreferences.svg|32px]] [[OpenSCAD_Preferences|Preferences]]: preferences available for the OpenSCAD tools.


== Limitations == <!--T:8-->
== Limitations == <!--T:8-->
Line 58: Line 96:
OpenSCAD works internally on meshes. Some operations which are useful on meshes are not meaningful on a BREP model and can not be fully supported. Among these are convex hull, minkowski sum, glide and subdiv. Currently we run the OpenSCAD binary in order to perform hull and minkwoski operations and import the result. This means that the involved geometry will be triangulated. In OpenSCAD non-uniform scaling is often used, which does not impose any problems when using meshes. In our geometry kernel geometric primitives (lines, circular sections, etc) are converted to BSpline prior to performing such deformations. Those BSplines are known to cause trouble in later boolean operations. An automatic solution is not available at the moment. Please feel free to post to the forum if you encounter such problems. Often such problems can be solved be remodeling small parts. A deformation of a cylinder can substituted by an extrusion of an ellipses.
OpenSCAD works internally on meshes. Some operations which are useful on meshes are not meaningful on a BREP model and can not be fully supported. Among these are convex hull, minkowski sum, glide and subdiv. Currently we run the OpenSCAD binary in order to perform hull and minkwoski operations and import the result. This means that the involved geometry will be triangulated. In OpenSCAD non-uniform scaling is often used, which does not impose any problems when using meshes. In our geometry kernel geometric primitives (lines, circular sections, etc) are converted to BSpline prior to performing such deformations. Those BSplines are known to cause trouble in later boolean operations. An automatic solution is not available at the moment. Please feel free to post to the forum if you encounter such problems. Often such problems can be solved be remodeling small parts. A deformation of a cylinder can substituted by an extrusion of an ellipses.


== Hints == <!--T:10-->
== Hints == <!--T:31-->

<!--T:10-->
When importing [[DXF|DXF]] set the Draft precision to a sensible amount as this will affect the detection of connected edges.
When importing [[DXF|DXF]] set the Draft precision to a sensible amount as this will affect the detection of connected edges.


Line 64: Line 104:
If FreeCAD crashes when importing CSG, it is strongly recommended that you enable "automatically check model after boolean operation" in {{MenuCommand|Menu → Edit → Preferences → Part Design → Model setting}}.
If FreeCAD crashes when importing CSG, it is strongly recommended that you enable "automatically check model after boolean operation" in {{MenuCommand|Menu → Edit → Preferences → Part Design → Model setting}}.


== Dependencies ==
=== Importing text ===


==== Prerequisites ====
In FreeCAD 0.19, the Ply (Python-Lex-Yacc) module, which is used to import CSG files was removed from the FreeCAD source code, as it is a third party library not developed by FreeCAD. As a result, you now need to install Ply yourself before using the OpenSCAD Workbench. When using the stable version of FreeCAD this dependency should be installed automatically in all platforms; in other cases, for example, when [[Compiling|compiling]] yourself you may have to install it from an online repository.


Importing OpenSCAD code with text requires that the font is '''''Installed''''' on your system.
In Debian/Ubuntu based systems this is done like this.
</translate>
{{Code|code=
sudo apt install python3-ply
}}
<translate>


On Windows, the font has to be added to the %WINDIR%/fonts directory - generally <nowiki>C:\Windows\Fonts</nowiki>. Clicking "Install" when viewing the font under Windows is not (always) sufficient for OpenSCAD.
The general installation in all platforms can be done from the Python package index.
</translate>
{{Code|code=
pip3 install --user ply
}}
<translate>


You can check which fonts are "Installed", by opening OpenSCAD as a standalone tool and checking the list in <nowiki>"Help > Font List"</nowiki>. You can check the Font Name known by OpenSCAD and the directory where these fonts are located.
== Tutorials == <!--T:15-->

After copying your font to the appropriate system directory, close and reopen OpenSCAD and verify that your font appears in the list, and that the name is exactly the one you are using.

==== How it works ====

Behind the scenes, FreeCAD gets the DXF file corresponding to the text from OpenSCAD.

That makes importing with text slow. FreeCAD and the File Explorer (Windows) can be unresponsive during the import.

At the end of the import you may have several lines with "0" appearing in the console. There are as many 0's as there are contours in your text. The more contours there are, the slower the import.

==== Test using a simple file first ====

Therefore it is best to first try the import with a simple test case, using a single letter for your font that lets you confirm it's the correct font (replace NameOfFont with your Font name):

<nowiki>
TESTFONT="NameOfFont";
linear_extrude(0.001) {
text("A", size=5, font=TESTFONT);
};
</nowiki>

==== Caveats/Detractors ====

The <nowiki>"use <FONT>;"</nowiki> statements in your source files are not effective when importing in FreeCAD. Under OpenSCAD, the effect of that "use" statement is that the provided font file is temporarily added to the list of known fonts.

OpenSCAD has itself some issues with fonts. For instance, it will interpret <nowiki>use <FONT>;</nowiki> only when it first opens the script, not when modified interactively.

Importing OpenSCAD files with text can have as side effect that some Parts "disappear". That probably indicates that your font is not found as in a few test cases it was shown that adding the font to the system directory made that issue disappear.

== Tutorials == <!--T:32-->

<!--T:15-->
* [[Import_OpenSCAD_code|Import OpenSCAD code]]
* [[Import_OpenSCAD_code|Import OpenSCAD code]]


== Links == <!--T:12-->
== Links == <!--T:33-->

<!--T:12-->
* OpenSCAD source code repository on [https://github.com/openscad/openscad GitHub]
* [https://freecadweb.org/tracker/search.php?tag_string=OpenSCAD Open tickets tagged "Openscad" on the FreeCAD bugtracker]
* [https://freecadweb.org/tracker/search.php?tag_string=OpenSCAD Open tickets tagged "Openscad" on the FreeCAD bugtracker]
* [http://www.thingiverse.com/tag:openscad Things tagged with "OpenSCAD" on Thingiverse]
* [http://www.thingiverse.com/tag:openscad Things tagged with "OpenSCAD" on Thingiverse]


<!--T:13-->
{{docnav|[[Mesh Module|Mesh Module]]|[[Part Module|Part Module]]|IconL=Workbench_Mesh.svg|IconR=Workbench_Part.svg}}


<!--T:22-->
<!--T:13-->
{{Docnav
{{OpenSCAD Tools navi}}
|[[Mesh_Workbench|Mesh Workbench]]
{{Userdocnavi}}
|[[Part_Workbench|Part Workbench]]
[[Category:Workbenches]]
|IconL=Workbench_Mesh.svg
|IconR=Workbench_Part.svg
}}


</translate>
</translate>
{{OpenSCAD Tools navi{{#translation:}}}}
{{Userdocnavi{{#translation:}}}}
[[Category:Workbenches{{#translation:}}]]

Revision as of 17:20, 28 November 2021

OpenSCAD workbench icon

Introduction

The OpenSCAD Workbench is intended to offer interoperability with the open source software OpenSCAD. This program is not distributed as part of FreeCAD, but should be installed to make full use of this workbench. OpenSCAD should not be confused with OpenCASCADE, which is the geometrical kernel that FreeCAD uses to build geometry on screen. The OpenCASCADE libraries are always needed to use FreeCAD, while the OpenSCAD executable is entirely optional.

It contains a CSG importer to open the CSG files from OpenSCAD, and an exporter to output a CSG based tree. Geometry which is not based on CSG operations will be exported as a mesh.

This workbench contains functions to modify the CSG feature tree and repair models. It also contains general purpose tools that do not require installation of OpenSCAD; they can be used in conjunction with other workbenches. For example, the Mesh Workbench internally uses the OpenSCAD functions to perform operations with meshes, as they are quite robust.

Dependencies

In FreeCAD 0.19, the Ply (Python-Lex-Yacc) module, which is used to import CSG files, was removed from the FreeCAD source code, as it is a third party library not developed by FreeCAD. As a result, you now need to install Ply before using the OpenSCAD Workbench. When using a pre-packaged, stable version of FreeCAD this dependency should be installed automatically in all platforms; in other cases, for example, when compiling from source, you may have to install it from an online repository.

In openSUSE this is done by:

sudo zypper install python3-ply

In Debian/Ubuntu based systems this is done like the following:

sudo apt install python3-ply

The general installation in all platforms can be done from the Python package index.

pip3 install --user ply

OpenSCAD language and file format

The OpenSCAD language allows the use of variables and loops. It allows you to specify sub-modules to reuse geometry and code. This high degree of flexibility makes parsing very complex. Currently the OpenSCAD Workbench cannot handle the OpenSCAD language natively. Instead, if OpenSCAD is installed, it can be used to convert the input to the CSG format, which is a subset of the OpenSCAD language, and can be used as the input to OpenSCAD for further processing. During conversion all parametric behavior is lost, meaning that all variable names are discarded, loops expanded, and mathematical expressions evaluated.

Tools

Preferences

  • Preferences: preferences available for the OpenSCAD tools.

Limitations

OpenSCAD creates constructive solid geometry, as well as imports mesh files and extrudes 2D geometry from DXF files. FreeCAD allows you to create CSG with primitives as well. The FreeCAD geometry kernel (OCCT) works using a boundary representation. Therefore conversion from CSG to BREP should, in theory, be possible whereas conversion from BREP to CSG is, in general, not.

OpenSCAD works internally on meshes. Some operations which are useful on meshes are not meaningful on a BREP model and can not be fully supported. Among these are convex hull, minkowski sum, glide and subdiv. Currently we run the OpenSCAD binary in order to perform hull and minkwoski operations and import the result. This means that the involved geometry will be triangulated. In OpenSCAD non-uniform scaling is often used, which does not impose any problems when using meshes. In our geometry kernel geometric primitives (lines, circular sections, etc) are converted to BSpline prior to performing such deformations. Those BSplines are known to cause trouble in later boolean operations. An automatic solution is not available at the moment. Please feel free to post to the forum if you encounter such problems. Often such problems can be solved be remodeling small parts. A deformation of a cylinder can substituted by an extrusion of an ellipses.

Hints

When importing DXF set the Draft precision to a sensible amount as this will affect the detection of connected edges.

If FreeCAD crashes when importing CSG, it is strongly recommended that you enable "automatically check model after boolean operation" in Menu → Edit → Preferences → Part Design → Model setting.

Importing text

Prerequisites

Importing OpenSCAD code with text requires that the font is Installed on your system.

On Windows, the font has to be added to the %WINDIR%/fonts directory - generally C:\Windows\Fonts. Clicking "Install" when viewing the font under Windows is not (always) sufficient for OpenSCAD.

You can check which fonts are "Installed", by opening OpenSCAD as a standalone tool and checking the list in "Help > Font List". You can check the Font Name known by OpenSCAD and the directory where these fonts are located.

After copying your font to the appropriate system directory, close and reopen OpenSCAD and verify that your font appears in the list, and that the name is exactly the one you are using.

How it works

Behind the scenes, FreeCAD gets the DXF file corresponding to the text from OpenSCAD.

That makes importing with text slow. FreeCAD and the File Explorer (Windows) can be unresponsive during the import.

At the end of the import you may have several lines with "0" appearing in the console. There are as many 0's as there are contours in your text. The more contours there are, the slower the import.

Test using a simple file first

Therefore it is best to first try the import with a simple test case, using a single letter for your font that lets you confirm it's the correct font (replace NameOfFont with your Font name):

  TESTFONT="NameOfFont";
  linear_extrude(0.001) {
    text("A", size=5, font=TESTFONT);
  };

Caveats/Detractors

The "use <FONT>;" statements in your source files are not effective when importing in FreeCAD. Under OpenSCAD, the effect of that "use" statement is that the provided font file is temporarily added to the list of known fonts.

OpenSCAD has itself some issues with fonts. For instance, it will interpret use <FONT>; only when it first opens the script, not when modified interactively.

Importing OpenSCAD files with text can have as side effect that some Parts "disappear". That probably indicates that your font is not found as in a few test cases it was shown that adding the font to the system directory made that issue disappear.

Tutorials

Links