Topological data scripting/it

Questa pagina descrive i diversi metodi per creare e modificare gli oggetti di tipo Parte tramite Python.

Se non si conosce ancora Python, prima di leggere questa pagina, è meglio leggere la pagina di introduzione a Python e quella in cui si decrive come funzionano gli script in FreeCAD.

Introduzione
Qui si spiega come controllare il Modulo Parte direttamente tramite l'interprete Python di FreeCAD, o tramite degli script esterni.

Se avete bisogno di ulteriori informazioni su come funzionano gli script in FreeCAD, potete consultare la sezione Script e la sezione Concetti base sugli script in FreeCAD.

Diagramma delle classi
Questa è una panoramica delle classi Linguaggio di Modellazione Unificato (UML) più importanti del modulo Parte:



Geometria
Gli oggetti geometrici sono le fondamenta per la costruzione di tutti gli oggetti topologici:


 * Geom Classe base degli oggetti geometrici
 * Line Linea retta in 3D, definita dal punto iniziale e dal punto finale
 * Circle Cerchio o arco definito dal centro, dal punto iniziale e dal punto finale
 * ...... E presto ancora altro

Topologia
Sono disponibili i seguenti tipi di dati topologici:


 * compound Un gruppo di qualsiasi tipo di oggetto topologico.
 * compsolid Un solido composito è un insieme di solidi collegati dalle loro facce. E' una estensione dei concetti wire e shell ai solidi.
 * solid Una parte di spazio limitato da shell. E' tridimensionale
 * shell Una serie di facce connesse nei loro bordi. Una shell (guscio) può essere aperta o chiusa.
 * face In 2D è una parte di un piano; in 3D è una parte di una superficie. La sua geometria è vincolata (delimitata/tagliata) dai suoi bordi.
 * wire Una serie di bordi (una polilinea) collegati tra di loro nei vertici. Può essere un profilo aperto o chiuso, secondo se i bordi sono interamente concatenati oppure no.
 * edge Un elemento topologico corrispondente ad una curva limitata. Un bordo è generalmente delimitato dai vertici. Ha una dimensione.
 * vertex Un elemento topologico corrispondente ad un punto. Esso non ha dimensioni.
 * shape Un termine generico che comprende tutti i precedenti.

Veloce esempio: Creare una topologia base


Creeremo ora una topologia tramite la costruzione della semplice geometria. Come caso di studio, utilizzeremo una forma come quella che si vede nella figura, composta da quattro vertici, due cerchi e due linee.

Creare la geometria
Per prima cosa dobbiamo creare le singole parti geometriche di questo contorno (wire). E' necessario che i vertici delle parti geometriche siano nella stessa posizione. In caso contrario, in seguito potremmo non essere in grado di collegare le parti geometriche in una topologia!

Quindi creiamo prima i punti:

Arco


Per creare un arco di cerchio prima creiamo un punto di supporto poi creiamo l'arco di cerchio tramite tre punti:

Linea


La linea può essere creata molto semplicemente tramite i punti:

Unire tutto
L'ultimo passaggio consiste nell'unire tutti gli elementi geometrici di base e produrre una forma topologica:

Creare un prisma
Ora si può estrudere il contorno nella direzione voluta e creare una forma 3D reale:

Mostrare il risultato
Per visualizzare il prisma:

Creare forme di base
Con i metodi "make..." del Modulo Parte è possibile creare facilmente oggetti topologici di base (chiamati anche forme primitive). Ad esempio, si può creare un cubo con: Altri metodi make... disponibili sono:
 * makeBox(l,w,h) -- Produce un box situato in p e rivolto nella direzione d con le dimensioni (l,w,h)
 * makeCircle(raggio) -- Crea un cerchio con un raggio dato
 * makeCone(raggio1,raggio2,altezza) -- Restituisce un cono con raggio e altezza dati
 * makeCylinder(raggio,altezza) -- Crea un cilindro con raggio e l'altezza prestabilite
 * makeLine((x1,y1,z1),(x2,y2,z2)) -- Crea una linea tra due punti
 * makePlane(lunghezza,larghezza) -- Crea un piano con lunghezza e larghezza
 * makePolygon(lista) -- Restituisce un poligono da una serie di punti
 * makeSphere(raggio) -- Crea una sfera di raggio dato
 * makeTorus(raggio1,raggio2) -- Crea un toro con raggi determinati

Per avere un elenco completo dei metodi disponibili con il modulo Parte consultare la pagina API di Parte (Part API in inglese).

Importare i moduli necessari
In primo luogo è necessario importare il modulo Parte per poter utilizzare i suoi contenuti in Python. Inoltre, importiamo anche il modulo Base dall'interno del modulo FreeCAD:

Creare un vettore
Per la costruzione di forme, i Vettori sono una delle parti di informazione più importanti. Di solito, ma non necessariamente sempre, essi contengono 3 numeri che sono le coordinate cartesiane x, y e z. È possibile creare un vettore nel modo seguente: Abbiamo appena creato un vettore nelle coordinate x=3, y=2, z=0. Nel modulo Parte, i vettori sono usati in tutte le parti. Le forme Parte usano anche un altro tipo di rappresentazione del punto, chiamato Vertex (Vertice), che in realtà non è altro che un contenitore per un vettore. Si accede al vettore di un vertice in questo modo:

Creare un bordo
Un bordo non è altro che una linea con due vertici: Nota: È anche possibile creare un bordo passando due vettori: È possibile trovare la lunghezza e il centro di un bordo in questo modo:

Mostrare la forma sullo schermo
Con le operazioni precedenti abbiamo creato un oggetto bordo, ma esso non è visibile da nessuna parte sullo schermo. Questo perché fino a qui abbiamo manipolato solo oggetti Python. La scena 3D di FreeCAD mostra solo quello che gli si chiede di visualizzare. Per farlo, usiamo questo semplice metodo: Nel nostro documento FreeCAD viene creato un oggetto, e la nostra forma "edge" viene attribuita ad esso. Utilizzare questo metodo ogni volta che si vuole visulizzare il proprio prodotto sullo schermo.

Creare un contorno
Un contorno è una polilinea e può essere creato da una serie di bordi o anche da una serie di contorni: Part.show(wire3) serve per visualizzare i 4 bordi che compongono il nostro contorno. Si possono facilmente recuperare altre informazioni utili con:

Creare una faccia
Sono valide solo le facce create da contorni chiusi. Nell'esempio, wire3 è un contorno chiuso, ma wire2 non è un contorno chiuso (vedi esempio precedente) Solamente le facce hanno un'area, non i contorni né i bordi.

Creare una circonferenza
Un cerchio può essere creato in questo semplice modo: Se si vuole crearlo in una determinata posizione e con una direzione prestabilita: ccircle verrà creato a distanza 10 dall'origine su x e sarà rivolto verso l'asse x. Nota: makeCircle accetta solo Base.Vector per la posizione e le normali, ma non tuple. È inoltre possibile creare una parte di cerchio fornendo un angolo iniziale e un angolo finale come: Unendo arc1 con arc2 (sono due semicerchi) si ottiene un cerchio completo. Gli angoli devono essere forniti in gradi, se avete angoli in radianti convertirli usando semplicemente la formula: gradi = radianti * 180/PI o utilizzando il modulo matematico di Python (ovviamente, dopo aver importato il modulo math):

Creare un arco attraverso dei punti
Purtroppo, per creare un arco lungo tre punti non esiste una funzione makeArc ma si deve usare la funzione Part.Arc. Fondamentalmente si può pensare come un arco che unisce il punto iniziale e finale passando per il punto medio. Part.Arc crea un oggetto arco nel quale deve essere chiamato .toShape per ottenere un oggetto bordo, allo stesso modo di quando si usa Part.Line al posto di Part.makeLine. Arc accetta solo punti Base.Vector, ma non tuple. arc_edge è ciò che vogliamo e che possiamo visualizzare con Part.show(arc_edge). Inoltre è possibile ottenere un arco utilizzando una porzione di un cerchio: Gli archi sono bordi validi, come le linee. Quindi possono essere usati anche nei contorni.

Creare un poligono
Un poligono è semplicemente un contorno composto da diversi bordi diritti. La funzione makePolygon prende una lista di punti e crea un contorno attraverso questi punti:

Creare una curva di Bezier
Le curve di Bézier sono utilizzate per modellare delle curve morbide utilizzando una serie di Poles (punti) e weight (pesi) opzionali. La funzione sottostante crea una Part.BezierCurve da una serie di punti FreeCAD.Vector. (Notare che gli indici di pole e di weight partono da 1, non da 0.)

Creare un piano
Un Piano è semplicemente una superficie piana rettangolare. Il metodo utilizzato per crearlo è questo: makePlane(lunghezza, larghezza, [start_pnt, dir_normal]). Per impostazione predefinita start_pnt=Vector (0,0,0) e dir_normal=Vector(0,0,1). Utilizzando dir_normal=Vector(0,0,1) creeremo il piano orientato come l'asse z, mentre con dir_normal=Vector(1,0,0) creeremo il piano orientato come l'asse x: BoundBox è il parallelepipedo che racchiude il piano e la cui diagonale parte da (3,0,0) e termina in (5,0,2). Qui lo spessore di BoundBox sull'asse y è zero, poiché la nostra forma è totalmente piatta.

Nota: makePlane accetta solo Base.Vector per start_pnt e dir_normal e non tuple

Creare una ellisse
Per creare un'ellisse ci sono diversi modi: Creates an ellipse with major radius 2 and minor radius 1 with the center in (0,0,0) Create a copy of the given ellipse Creates an ellipse centered on the point Center, where the plane of the ellipse is defined by Center, S1 and S2, its major axis is defined by Center and S1, its major radius is the distance between Center and S1, and its minor radius is the distance between S2 and the major axis. Creates an ellipse with major and minor radii MajorRadius and MinorRadius, and located in the plane defined by Center and the normal (0,0,1) In the above code we have passed S1, S2 and center. Similarly to Arc, Ellipse also creates an ellipse object but not edge, so we need to convert it into edge using toShape to display.

Note: Arc only accepts Base.Vector for points but not tuples for the above Ellipse constructor we have passed center, MajorRadius and MinorRadius

Creating a Torus
Using the method makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]). By default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0,angle2=360 and angle=360. Consider a torus as small circle sweeping along a big circle. Radius1 is the radius of big cirlce, radius2 is the radius of small circle, pnt is the center of torus and dir is the normal direction. angle1 and angle2 are angles in radians for the small circle, the last parameter angle is to make a section of the torus: The above code will create a torus with diameter 20(radius 10) and thickness 4 (small cirlce radius 2) The above code will create a slice of the torus The above code will create a semi torus, only the last parameter is changed i.e the angle and remaining angles are defaults. Giving the angle 180 will create the torus from 0 to 180, that is, a half torus.

Creating a box or cuboid
Using makeBox(length,width,height,[pnt,dir]). By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)

Creating a Sphere
Using makeSphere(radius,[pnt, dir, angle1,angle2,angle3]). By default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=-90, angle2=90 and angle3=360. angle1 and angle2 are the vertical minimum and maximum of the sphere, angle3 is the sphere diameter itself.

Creating a Cylinder
Using makeCylinder(radius,height,[pnt,dir,angle]). By default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360

Creating a Cone
Using makeCone(radius1,radius2,height,[pnt,dir,angle]). By default pnt=Vector(0,0,0), dir=Vector(0,0,1) and angle=360

Modifying shapes
There are several ways to modify shapes. Some are simple transformation operations such as moving or rotating shapes, other are more complex, such as unioning and subtracting one shape from another. Be aware that

Translating a shape
Translating is the act of moving a shape from one place to another. Any shape (edge, face, cube, etc...) can be translated the same way: This will move our shape "myShape" 2 units in the x direction.

Rotating a shape
To rotate a shape, you need to specify the rotation center, the axis, and the rotation angle: The above code will rotate the shape 180 degrees around the Z Axis.

Generic transformations with matrixes
A matrix is a very convenient way to store transformations in the 3D world. In a single matrix, you can set translation, rotation and scaling values to be applied to an object. For example: Note: FreeCAD matrixes work in radians. Also, almost all matrix operations that take a vector can also take 3 numbers, so those 2 lines do the same thing: When our matrix is set, we can apply it to our shape. FreeCAD provides 2 methods to do that: transformShape and transformGeometry. The difference is that with the first one, you are sure that no deformations will occur (see "scaling a shape" below). So we can apply our transformation like this: or

Scaling a shape
Scaling a shape is a more dangerous operation because, unlike translation or rotation, scaling non-uniformly (with different values for x, y and z) can modify the structure of the shape. For example, scaling a circle with a higher value horizontally than vertically will transform it into an ellipse, which behaves mathematically very differenty. For scaling, we can't use the transformShape, we must use transformGeometry:

Subtraction
Subtracting a shape from another one is called "cut" in OCC/FreeCAD jargon and is done like this:

Intersection
The same way, the intersection between 2 shapes is called "common" and is done this way:

Union
Union is called "fuse" and works the same way:

Section
A Section is the intersection between a solid shape and a plane shape. It will return an intersection curve, a compound with edges

Extrusion
Extrusion is the act of "pushing" a flat shape in a certain direction resulting in a solid body. Think of a circle becoming a tube by "pushing it out": If your circle is hollow, you will obtain a hollow tube. If your circle is actually a disc, with a filled face, you will obtain a solid cylinder:

Exploring shapes
You can easily explore the topological data structure: By typing the lines above in the python interpreter, you will gain a good understanding of the structure of Part objects. Here, our makeBox command created a solid shape. This solid, like all Part solids, contains faces. Faces always contain wires, which are lists of edges that border the face. Each face has at least one closed wire (it can have more if the face has a hole). In the wire, we can look at each edge separately, and inside each edge, we can see the vertexes. Straight edges have only two vertexes, obviously.

Edge analysis
In case of an edge, which is an arbitrary curve, it's most likely you want to do a discretization. In FreeCAD the edges are parametrized by their lengths. That means you can walk an edge/curve by its length: Now you can access a lot of properties of the edge by using the length as a position. That means if the edge is 100mm long the start position is 0 and the end position 100.

Using the selection
Here we see now how we can use the selection the user did in the viewer. First of all we create a box and shows it in the viewer Select now some faces or edges. With this script you can iterate all selected objects and their sub elements: Select some edges and this script will calculate the length:

Complete example: The OCC bottle
A typical example found on the OpenCasCade Getting Started Page is how to build a bottle. This is a good exercise for FreeCAD too. In fact, you can follow our example below and the OCC page simultaneously, you will understand well how OCC structures are implemented in FreeCAD. The complete script below is also included in FreeCAD installation (inside the Mod/Part folder) and can be called from the python interpreter by typing:

The complete script
Here is the complete MakeBottle script:

Detailed explanation
We will need,of course, the Part module, but also the FreeCAD.Base module, which contains basic FreeCAD structures like vectors and matrixes. Here we define our makeBottle function. This function can be called without arguments, like we did above, in which case default values for width, height, and thickness will be used. Then, we define a couple of points that will be used for building our base profile. Here we actually define the geometry: an arc, made of 3 points, and two line segments, made of 2 points. Remember the difference between geometry and shapes? Here we build shapes out of our construction geometry. 3 edges (edges can be straight or curved), then a wire made of those three edges. Until now we built only a half profile. Easier than building the whole profile the same way, we can just mirror what we did, and glue both halfs together. So we first create a matrix. A matrix is a very common way to apply transformations to objects in the 3D world, since it can contain in one structure all basic transformations that 3D objects can suffer (move, rotate and scale). Here, after we create the matrix, we mirror it, and we create a copy of our wire with that transformation matrix applied to it. We now have two wires, and we can make a third wire out of them, since wires are actually lists of edges. Now that we have a closed wire, it can be turned into a face. Once we have a face, we can extrude it. Doing so, we actually made a solid. Then we apply a nice little fillet to our object because we care about good design, don't we? Then, the body of our bottle is made, we still need to create a neck. So we make a new solid, with a cylinder. The fuse operation, which in other apps is sometimes called union, is very powerful. It will take care of gluing what needs to be glued and remove parts that need to be removed. Then, we return our Part solid as the result of our function. That Part solid, like any other Part shape, can be attributed to an object in a FreeCAD document, with: or, more simple:

Box pierced
Here a complete example of building a box pierced.

The construction is done side by side and when the cube is finished, it is hollowed out of a cylinder through.

Loading and Saving
There are several ways to save your work in the Part module. You can of course save your FreeCAD document, but you can also save Part objects directly to common CAD formats, such as BREP, IGS, STEP and STL.

Saving a shape to a file is easy. There are exportBrep, exportIges, exportStl and exportStep methods availables for all shape objects. So, doing: this will save our box into a STEP file. To load a BREP, IGES or STEP file, simply do the contrary: To convert an .stp in .igs file simply : Note that importing or opening BREP, IGES or STEP files can also be done directly from the File -> Open or File -> Import menu, while exporting is with File -> Export