Builtin modules: Difference between revisions

From FreeCAD Documentation
No edit summary
Line 1: Line 1:
This page presents more in-depth information over the built-in FreeCAD modules, and what are the functions and properties availible to you. This page is not a complete list of all the contents of these modules, and, because of the fast evolution of FreeCAD, the information presented here might be slightly outdated, but it should give you a good overview of the possibilities. For complete list of the modules content, use the dir(module) function in the interpreter.
This page presents more in-depth information over the built-in FreeCAD modules, and what are the functions and properties availible to you. This page is not a complete list of all the contents of these modules, and, because of the fast evolution of FreeCAD, the information presented here might be slightly outdated, but it should give you a good overview of the possibilities. For complete list of the modules content, use the dir(module) function in the interpreter.


=== The FreeCAD module ===
=== [[FreeCAD_API|The FreeCAD module]] ===


=== [[Base_API|Base]] ===
This is the principal (root) module of FreeCAD. It can also be called by "App" from the FreeCAD interpreter. It contains everything that is needed to manipulate documents and their contents (objects).


=== [[Vector_API|Vectors]] ===
Example:
import FreeCAD
print FreeCAD.listDocuments()
mydoc = FreeCAD.activeDocument()


=== [[Matrix_API|Matrixes]] ===
{{APIFunction|ConfigDump| |Prints a dictionnnary containing all the FreeCAD configuration environment.| }}


=== [[Console_API|Console module]] ===
{{APIFunction|ConfigGet|[string]|Returns the value of the given key. If no key is given, the complete configuration is returned|A string.}}


=== [[FreeCADGui_API|The FreeCADGui Module]] ===
{{APIFunction|ConfigSet|string, string|Set the given key (first string) to the given value (second string).| }}


=== [[Selection_API|Selection module]] ===
{{APIFunction|Version| |Prints the FreeCAD version.| }}


=== [[Placement_API|Placement]] ===
{{APIFunction|activeDocument| ||Return the active document or None if there is no active document.|A FreeCAD Document.}}


=== [[Object_API|Document Objects]] ===
{{APIFunction|addExportType|string, string|Adds a new export file type to FreeCAD. The first string must be formatted like this example: "Word Document (*.doc)". The second string is the name of a python script/module containing an export() function.| }}


=== [[ViewObject_API|View Objects]] ===
{{APIFunction|addImportType|string, string|Adds a new import file type to FreeCAD, works the same way as addExportType, the handling python module must contain an open() and/or an import() function.| }}

{{APIFunction|closeDocument|Document name|Closes the given document| }}

{{APIFunction|getDocument|Document name|Returns a document or raise an exception if there is no document with the given name.| }}

{{APIFunction|getExportType|string|Returns the name of the module that can export the specified filetype.| A string.}}

{{APIFunction|getImportType|string|Returns the name of the module that can import the specified filetype.|A string.}}

{{APIFunction|listDocuments| |Returns a list of names of all documents.|A list of names.}}

{{APIFunction|newDocument|[string]|Creates and returns a new document with a given name. The document name must be unique, which is checked automatically. If no name is supplied, the document will be named "Untitled".|The newly created document.}}

{{APIFunction|open|string|See openDocument| }}

{{APIFunction|openDocument|filepath|Creates and returns a document and load a project file into the document. The string argument must point to an existing file. If the file doesn't exist or the file cannot be loaded an I/O exception is thrown. In this case the created document is kept, but will be empty.|The opened FreeCAD Document.}}

{{APIFunction|setActiveDocument|Document name|Set the active document by its name.| }}

=== Base ===

The Base module is contained inside the FreeCAD module and contains constructors for different types of objects heavily used in FreeCAD.

{{APIClass|BoundBox|[Xmin,Ymin,Zmin,Xmax,Ymax,Zmax] ) or ( Tuple, Tuple ) or ( Vector, Vector|Creates a bounding box. A bounding box is an orthographic cube which is a way to describe outer boundaries. You get a bounding box from a lot of 3D types. It is often used to check if a 3D entity lies in the range of another object. Checking for boundig interference first can save a lot of computing time!}}

{{APIClass|Matrix| |Creates a 4x4 matrix, that can be used to apply transformations to objects.}}

{{APIClass|Vector|x,y,z|Creates a FreeCAD 3D vector, representing a 3D point or a direction.}}

=== Vectors ===

Vectors are used everywhere in FreeCAD.

Example:
v=FreeCAD.Vector()
v=FreeCAD.Vector(1,0,0)
v=FreeCAD.Base.Vector()
v2 = FreeCAD.Vector(3,2,-5)
v3 = v.add(v2)
print v3.Length

{{APIProperty|Length|returns the length of the vector.}}

{{APIFunction|add|Vector|adds another vector to this one|the sum of both vectors.}}

{{APIFunction|cross|Vector| |the crossproduct between two vectors.}}

{{APIFunction|distanceToLine|Vector1,Vector2| |the distance between the vector and a line between Vector1 and Vector2.}}

{{APIFunction|distanceToPlane|Vector1,Vector2| |the distance between the vector and a plane defined by a point and a normal.}}

{{APIFunction|dot|Vector| |the dot product between 2 vectors.}}

{{APIFunction|getAngle|Vector| |the angle in radians between 2 vectors.}}

{{APIFunction|multiply|Float|multiplies (scales) a vector by the given factor|nothing.}}

{{APIFunction|normalize| |normalizes a vector (sets its length to 1.0).|nothing.}}

{{APIFunction|projectToLine|Vector1,Vector2|projects the vector on a line between Vector1 and Vector2.|nothing.}}

{{APIFunction|projectToPlane|Vector1,Vector2|projects the vector on a plane defined by a point and a normal.|nothing.}}

{{APIFunction|scale|Float,Float,Float|Same as multiply but lets specify different values for x, y and z directions.|nothing.}}

{{APIFunction|sub|Vector|subtracts another vector from the first one.|the resulting vector.}}

{{APIProperty|x|the x coordinate of a vector.}}

{{APIProperty|y|the y coordinate of a vector.}}

{{APIProperty|z|the z coordinate of a vector.}}

=== Matrixes ===

4x4 Matrixes are used everywhere throughout FreeCAD and can be created by one of the following manners:

m=FreeCAD.Matrix()
m=FreeCAD.Base.Matrix()
print m.A21()

{{APIFunction|A| | |all the matrix elements.}}

{{APIFunction|A11| | |a matrix element.}}

{{APIFunction|A12| | |a matrix element.}}

{{APIFunction|A13| | |a matrix element.}}

{{APIFunction|A14| | |a matrix element.}}

{{APIFunction|A21| | |a matrix element.}}

{{APIFunction|A22| | |a matrix element.}}

{{APIFunction|A23| | |a matrix element.}}

{{APIFunction|A24| | |a matrix element.}}

{{APIFunction|A31| | |a matrix element.}}

{{APIFunction|A32| | |a matrix element.}}

{{APIFunction|A33| | |a matrix element.}}

{{APIFunction|A34| | |a matrix element.}}

{{APIFunction|A41| | |a matrix element.}}

{{APIFunction|A42| | |a matrix element.}}

{{APIFunction|A43| | |a matrix element.}}

{{APIFunction|A44| | |a matrix element.}}

{{APIFunction|determinant|Float|Computes the determinant of the matrix|the matrix determinant.}}

{{APIFunction|inverse| |Computes the inverse matrix, if possible|a Matrix}}

{{APIFunction|invert| |Computes the inverse matrix, if possible|a Matrix}}

{{APIFunction|move|Vector|Moves the matrix along the vector|nothing.}}

{{APIFunction|multiply|Matrix or Vector|Multiplies a matrix or vector with this matrix|nothing.}}

{{APIFunction|rotateX|Float|rotates the matrix around X axis (in radians)|nothing.}}

{{APIFunction|rotateY|Float|rotates the matrix around Y axis (in radians)|nothing.}}

{{APIFunction|rotateZ|Float|rotates the matrix around Z axis (in radians)|nothing.}}

{{APIFunction|scale|Vector|Scales the matrix with the vector|nothing.}}

{{APIFunction|transform|Vector or Matrix|returns the dot product of the two vectors| }}

{{APIFunction|unity| |makes this matrix to unity|nothing.}}

=== Console module ===

This module is contained inside the FreeCAD module and contains methods to send text to FreeCAD's output console and status bar. The messages will have different color if they are message, warning or error. Example:

import FreeCAD
FreeCAD.PrintMessage("Hello World!\n")

{{APIFunction|GetStatus|"Log" or "Msg" or "Wrn" or "Err"|Get the status for either Log, Msg, Wrn or Error for an observer|a status string.}}
{{APIFunction|PrintError|string|Prints an error message to the output|nothing}}
{{APIFunction|PrintLog|string|Prints a log message to the output|nothing}}
{{APIFunction|PrintMessage|string|Prints a message to the output|nothing}}
{{APIFunction|PrintWarning|string|Prints a warning to the output|nothing}}
{{APIFunction|SetStatus|string|Set the stats for either Log, Msg, Wrn or Error for an observer| }}

=== The FreeCADGui Module ===

This module is the counterpart of the FreeCAD module. It contains everything related to the User interface and the 3D views. Example:

import FreeCADGui
doc = FreeCADGui.activeDocument()

{{APIFunction|activateWorkbench|string|Activates a workbench by name|nothing}}
{{APIFunction|activeDocument| | |the active document or None if no one exists}}
{{APIFunction|activeWorkbench| | |the active workbench object}}
{{APIFunction|addCommand|string, object|Adds a FreeCAD command. String is the name of the command and object is a classname defining the command| }}
{{APIFunction|addIcon|string, string or list|Adds an icon as file name or in XPM format to the system| }}
{{APIFunction|addIconPath|string|Add a new path to the system where to find icon files| }}
{{APIFunction|addPreferencePage|string,string|Adds a UI form to the preferences dialog. The first argument specifies the file name and the second specifies the group name| }}
{{APIFunction|addWorkbench|string, object|Adds a workbench under a defined name. The string is the workbench name and the object is a classname defining the workbench| }}
{{APIFunction|createDialog|string|Opens a UI file| }}
{{APIFunction|getDocument|string|Gets a document by its name|the document}}
{{APIFunction|getWorkbench|string|Gets a workbench by its name|the workbench}}
{{APIFunction|insert|string|Open a macro, Inventor or VRML file|the document}}
{{APIFunction|listWorkbenches| |Shows a list of all workbenches|a list}}
{{APIFunction|open|string|Opens a macro, Inventor or VRML file|the openend document}}
{{APIFunction|removeWorkbench|string|Removes a workbench by name| }}
{{APIFunction|runCommand|string|Runs a FreeCAD command by name| }}
{{APIFunction|updateGui| |Updates the main window and all its windows| }}

=== Selection module ===

The selection submodule is part of the FreeCADGui module. Example:

import FreeCADGui
sel = FreeCADGui.Selection.getSelection()

{{APIFunction|addSelection|FreeCAD.Object|Adds an object to the selection| }}
{{APIFunction|clearSelection|[string]|Clears the selection of the given document name. If no document is given the complete selection is cleared.| }}
{{APIFunction|getSelection|[string]|Returns a list of selected objects for a given document name. If no document is given the complete selection is returned.|a list of objects}}
{{APIFunction|isSelected|FreeCAD.Object|Checks if a given object is selected| }}
{{APIFunction|removeSelection|FreeCAD.Object|Removes an object from the selection| }}

=== Placement ===

A placement in FreeCAD is an object defining a position and a rotation. A placement can then be added to a FreeCAD Object, to orient/position it in the document. Example:

myObj = FreeCAD.ActiveDocument.ActiveObject
pl = FreeCAD.Placement()
pl.move(FreeCAD.Vector(2,0,0))
myObj.Placement = pl

{{APIClass|Placement| ) or (Placement) or (Matrix) or (Base, Rotation) or (Base,Rotation,Center) or (Base,Axis,Angle|Constructs a placement, empty or with the given arguments, or as a copy of the given placement.}}
{{APIProperty|Base|a vector representing the Placement's position.}}
{{APIProperty|Rotation|a quaternion representing the Placement's rotation.}}
{{APIFunction|inverse| |computes the inverse placement|a placement.}}
{{APIFunction|move|Vector|moves the Placement along the given vector|nothing}}
{{APIFunction|multVec|Vector|applies the Placement to the given vector|the resulting vector.}}
{{APIFunction|multiply|Placement|multiplies this placement with another one|the resulting placement.}}
{{APIFunction|toMatrix| | |a matrix representing the Placement's transformation.}}

=== Document Objects ===

Being parametric, document objects in FreeCAD can have a lot of additional properties, but these are the basic ones, present in every FreeCAD Document Object. Objects can be retrieved simply by their name. Example:

myObj = FreeCAD.ActiveDocument.myObjectName
print myObj.PropertiesList

{{APIProperty|Content|an XML representation of the properties of an object.}}
{{APIProperty|Label|Gets/sets the objects label. The string can be unicode.}}
{{APIProperty|Name|the unique name of an object.}}
{{APIProperty|Placement|Gets/sets the Placement of an object. A placement defines an orientation (rotation) and a position (base) in 3D space. It is used when no scaling or other distortion is needed.}}
{{APIProperty|Pos|the position part of the placement}}
{{APIProperty|PropertiesList|a list of the properties of an object}}
{{APIProperty|State|the FreeCAD state of an object (ie. if it needs to be recomputed)}}
{{APIProperty|Type|a string describing the type of an object}}
{{APIProperty|ViewObject|the associated View Provider (FreeCADGUI object) of an object}}
{{APIFunction|getAllDerivedFrom| | |all descentences of this object}}
{{APIFunction|getDocumentationOfProperty| | |the documentation string of the property of this class.}}
{{APIFunction|getGroupOfProperty| | |the name of the group which the property belongs to in this class. The properties sorted in differnt named groups for convenience.}}
{{APIFunction|getPropertyByName| | |the value of a named property.}}
{{APIFunction|getTypeOfProperty| | |the type of a named property. This can be (Hidden,ReadOnly,Output) or any combination.}}
{{APIFunction|isDerivedFrom| | |True if given type is a father}}
{{APIFunction|purgeTouched| |Marks the object as unchanged| }}
{{APIFunction|touch| |Marks the object as changed (touched)| }}

=== View Objects ===

When the GUI is up, each object in the FreeCAD document has an associated ViewObject, that resides in the FreeCADGui document counterpart. A view object can be retrieved by two ways. Example:

myViewObj = FreeCAD.ActiveDocument.myObjectName.ViewObject
myViewObj = FreeCADGui.ActiveDocument.myObjectName
print myViewObj.IV

{{APIProperty|Annotation|the annotation node of a ViewObject}}
{{APIProperty|BoundingBox|the bounding box}}
{{APIProperty|Content|an XML representation of a ViewObject's properties}}
{{APIProperty|DisplayMode|the current display mode}}
{{APIProperty|IV|an Inventor representation of the ViewObject}}
{{APIProperty|Object|the associated FreeCAD Document Object of this ViewObject}}
{{APIProperty|PropertiesList|a list of properties of this ViewObject}}
{{APIProperty|RootNode|the Inventor node of this ViewObject (pivy.coin object)}}
{{APIProperty|Selectable|True if the object is selectable}}
{{APIProperty|Type|the type of this ViewObject}}
{{APIProperty|Visibility|True if the viewObject is visible}}
{{APIFunction|getAllDerivedFrom| | |all descentences of this object}}
{{APIFunction|getDocumentationOfProperty| | |the documentation string of the property of this class.}}
{{APIFunction|getGroupOfProperty| | |the name of the group which the property belongs to in this class. The properties sorted in differnt named groups for convenience.}}
{{APIFunction|getPropertyByName| | |the value of a named property.}}
{{APIFunction|getTypeOfProperty| | |the type of a named property. This can be (Hidden,ReadOnly,Output) or any combination.}}
{{APIFunction|hide| |Hides the object.| }}
{{APIFunction|isDerivedFrom|string|Checks if this object is derived from the given object type|True if given type is a father}}
{{APIFunction|isVisible| |Checks if the object is visible|a boolean}}
{{APIFunction|listDisplayModes| |Shows a list of all display modes|a list}}
{{APIFunction|setTransformation|coin.SoTransform|Sets a transformation on the Inventor node|nothing}}
{{APIFunction|show| |Shows the object if hidden|nothing}}
{{APIFunction|toString| | |a string representation of the Inventor node}}
{{APIFunction|update| |Updates the view representation of the object| }}


[[Category:API]]
[[Category:API]]

Revision as of 19:08, 12 August 2010

This page presents more in-depth information over the built-in FreeCAD modules, and what are the functions and properties availible to you. This page is not a complete list of all the contents of these modules, and, because of the fast evolution of FreeCAD, the information presented here might be slightly outdated, but it should give you a good overview of the possibilities. For complete list of the modules content, use the dir(module) function in the interpreter.

The FreeCAD module

Base

Vectors

Matrixes

Console module

The FreeCADGui Module

Selection module

Placement

Document Objects

View Objects