Functions | |
| def | compare_objects (obj1, obj2) |
| def | convert_draft_texts (textslist=[]) |
| def | epsilon () |
| def | filter_objects_for_modifiers (objects, isCopied=False) |
| def | find_doc (doc=None) |
| def | find_object (obj, doc=None) |
| def | get_clone_base (obj, strict=False) |
| def | get_DXF (obj, direction=None) |
| def | get_group_contents (objectslist, walls=False, addgroups=False, spaces=False, noarchchild=False) |
| def | get_group_names () |
| def | get_movable_children (objectslist, recursive=True) |
| def | get_objects_of_type (objects, typ) |
| def | get_param (param, default=None) |
| def | get_param_type (param) |
| def | get_real_name (name) |
| def | get_rgb (color, testbw=True) |
| def | get_type (obj) |
| def | get_windows (obj) |
| def | is_clone (obj, objtype, recursive=False) |
| def | is_closed_edge (edge_index, object) |
| def | load_svg_patterns () |
| def | precision () |
| def | print_header (name, description, debug=True) |
| def | print_shape (shape) |
| def | set_param (param, value) |
| def | shapify (obj) |
| def | string_encode_coin (ustr) |
| def | svg_patterns () |
| def | tolerance () |
| def | type_check (args_and_types, name="?") |
| def | ungroup (obj) |
| def | use_instead (function, version="") |
| def | utf8_decode (text) |
Variables | |
| list | ARROW_TYPES = ["Dot", "Circle", "Arrow", "Tick", "Tick-2"] |
| list | arrowtypes = ARROW_TYPES |
| def | compareObjects = compare_objects |
| def | convertDraftTexts = convert_draft_texts |
| def | filterObjectsForModifiers = filter_objects_for_modifiers |
| def | getCloneBase = get_clone_base |
| def | getDXF = get_DXF |
| def | getGroupContents = get_group_contents |
| def | getGroupNames = get_group_names |
| def | getMovableChildren = get_movable_children |
| def | getObjectsOfType = get_objects_of_type |
| def | getParam = get_param |
| def | getParamType = get_param_type |
| def | getRealName = get_real_name |
| def | getrgb = get_rgb |
| def | getType = get_type |
| def | getWindows = get_windows |
| def | isClone = is_clone |
| def | isClosedEdge = is_closed_edge |
| def | loadSvgPatterns = load_svg_patterns |
| def | printShape = print_shape |
| def | setParam = set_param |
| def | stringencodecoin = string_encode_coin |
| def | svgpatterns = svg_patterns |
| def | typecheck = type_check |
Function Documentation
◆ compare_objects()
| def draftutils.utils.compare_objects | ( | obj1, | |
| obj2 | |||
| ) |
Print the differences between 2 objects.
The two objects are compared through their `TypeId` attribute,
or by using the `get_type` function.
If they are the same type their properties are compared
looking for differences.
Neither `Shape` nor `Label` attributes are compared.
Parameters
----------
obj1 : App::DocumentObject
Any type of scripted object.
obj2 : App::DocumentObject
Any type of scripted object.
References draftutils.utils.get_type(), and draftutils.utils.getType.
◆ convert_draft_texts()
| def draftutils.utils.convert_draft_texts | ( | textslist = [] | ) |
converts the given Draft texts (or all that is found in the active document) to the new object This function was already present at splitting time during v 0.19
◆ epsilon()
| def draftutils.utils.epsilon | ( | ) |
Return a small number based on the tolerance for use in comparisons.
The epsilon value is used in floating point comparisons. Use with caution.
::
denom = 10**tolerance
num = 1
epsilon = num/denom
Returns
-------
float
1/(10**tolerance)
References draftutils.utils.tolerance().
◆ filter_objects_for_modifiers()
| def draftutils.utils.filter_objects_for_modifiers | ( | objects, | |
isCopied = False |
|||
| ) |
References Gui.getMainWindow().
◆ find_doc()
| def draftutils.utils.find_doc | ( | doc = None | ) |
Return the active document or find a document by name.
Parameters
----------
doc: App::Document or str, optional
The document that will be searched in the session.
It defaults to `None`, in which case it tries to find
the active document.
If `doc` is a string, it will try to get the document by `Name`.
Returns
-------
bool, App::Document
A tuple containing the information on whether the search
was successful. In this case, the boolean is `True`,
and the second value is the document instance.
False, None
If there is no active document, or the string in `doc`
doesn't correspond to an open document in the session.
Referenced by draftutils.utils.find_object().
◆ find_object()
| def draftutils.utils.find_object | ( | obj, | |
doc = None |
|||
| ) |
Find object in the document, inclusive by Label.
Parameters
----------
obj: App::DocumentObject or str
The object to search in `doc`.
Or if the `obj` is a string, it will search the object by `Label`.
Since Labels are not guaranteed to be unique, it will get the first
object with that label in the document.
doc: App::Document or str, optional
The document in which the object will be searched.
It defaults to `None`, in which case it tries to search in the
active document.
If `doc` is a string, it will search the document by `Name`.
Returns
-------
bool, App::DocumentObject
A tuple containing the information on whether the search
was successful. In this case, the boolean is `True`,
and the second value is the object found.
False, None
If the object doesn't exist in the document.
References draftutils.utils.find_doc().
◆ get_clone_base()
| def draftutils.utils.get_clone_base | ( | obj, | |
strict = False |
|||
| ) |
Return the object cloned by this object, if any.
Parameters
----------
obj: App::DocumentObject
Any type of object.
strict: bool, optional
It defaults to `False`.
If it is `True`, and this object is not a clone,
this function will return `False`.
Returns
-------
App::DocumentObject
It `obj` is a `Draft Clone`, it will return the first object
that is in its `Objects` property.
If `obj` has a `CloneOf` property, it will search iteratively
inside the object pointed to by this property.
obj
If `obj` is not a `Draft Clone`, nor it has a `CloneOf` property,
it will return the same `obj`, as long as `strict` is `False`.
False
It will return `False` if `obj` is not a clone,
and `strict` is `True`.
References draftutils.utils.get_type().
◆ get_DXF()
| def draftutils.utils.get_DXF | ( | obj, | |
direction = None |
|||
| ) |
getDXF(object,[direction]): returns a DXF entity from the given object. If direction is given, the object is projected in 2D.
References draftutils.utils.getDXF, draftutils.utils.getType, DraftVecUtils.isNull(), and DraftVecUtils.project().
◆ get_group_contents()
| def draftutils.utils.get_group_contents | ( | objectslist, | |
walls = False, |
|||
addgroups = False, |
|||
spaces = False, |
|||
noarchchild = False |
|||
| ) |
Return a list of objects from expanding the input groups.
The function accepts any type of object, although it is most useful
with "groups", as it is meant to unpack the objects inside these groups.
Parameters
----------
objectslist : list
If any object in the list is a group, its contents (`obj.Group`)
are extracted and added to the output list.
The "groups" are objects derived from `'App::DocumentObjectGroup'`,
but they can also be `'App::Part'`, or `'Building'`, `'BuildingPart'`,
`'Space'`, and `'Site'` from the Arch Workbench.
Single items that aren't groups are added to the output list
as is.
walls : bool, optional
It defaults to `False`.
If it is `True`, Wall and Structure objects (Arch Workbench)
are treated as groups; they are scanned for Window, Door,
and Rebar objects, and these are added to the output list.
addgroups : bool, optional
It defaults to `False`.
If it is `True`, the group itself is kept as part of the output list.
spaces : bool, optional
It defaults to `False`.
If it is `True`, Arch Spaces are treated as groups,
and are added to the output list.
noarchchild : bool, optional
It defaults to `False`.
If it is `True`, the objects inside Building and BuildingParts
(Arch Workbench) aren't added to the output list.
Returns
-------
list
The list of objects from each group present in `objectslist`,
plus any other individual object given in `objectslist`.
References draftutils.utils.getGroupContents, draftutils.utils.getType, and draftutils.utils.getWindows.
◆ get_group_names()
| def draftutils.utils.get_group_names | ( | ) |
Return a list of names of existing groups in the document.
Returns
-------
list of str
A list of names of objects that are "groups".
These are objects derived from `'App::DocumentObjectGroup'`
or which are of types `'Floor'`, `'Building'`, or `'Site'`
(from the Arch Workbench).
Otherwise, return an empty list.
References draftutils.utils.getType.
◆ get_movable_children()
| def draftutils.utils.get_movable_children | ( | objectslist, | |
recursive = True |
|||
| ) |
Return a list of objects with child objects that move with a host.
Builds a list of objects with all child objects (`obj.OutList`)
that have their `MoveWithHost` attribute set to `True`.
This function is mostly useful for Arch Workbench objects.
Parameters
----------
objectslist : list of App::DocumentObject
A single scripted object or list of objects.
recursive : bool, optional
It defaults to `True`, in which case the function
is called recursively to also extract the children of children
objects.
Otherwise, only direct children of the input objects
are added to the output list.
Returns
-------
list
List of children objects that have their `MoveWithHost` attribute
set to `True`.
References draftutils.utils.getMovableChildren, and draftutils.utils.getType.
◆ get_objects_of_type()
| def draftutils.utils.get_objects_of_type | ( | objects, | |
| typ | |||
| ) |
Return only the objects that match the type in the list of objects.
Parameters
----------
objects : list of App::DocumentObject
A list of objects which will be tested.
typ : str
A string that indicates a type. This should be one of the types
that can be returned by `get_type`.
Returns
-------
list of objects
Only the objects that match `typ` will be added to the output list.
References draftutils.utils.getType.
◆ get_param()
| def draftutils.utils.get_param | ( | param, | |
default = None |
|||
| ) |
Return a parameter value from the current parameter database.
The parameter database is located in the tree
::
'User parameter:BaseApp/Preferences/Mod/Draft'
In the case that `param` is `'linewidth'` or `'color'` it will get
the values from the View parameters
::
'User parameter:BaseApp/Preferences/View/DefaultShapeLineWidth'
'User parameter:BaseApp/Preferences/View/DefaultShapeLineColor'
Parameters
----------
param : str
A string that indicates a parameter in the parameter database.
default : optional
It indicates the default value of the given parameter.
It defaults to `None`, in which case it will use a specific
value depending on the type of parameter determined
with `get_param_type`.
Returns
-------
int, or str, or float, or bool
Depending on `param` and its type, by returning `ParameterGrp.GetInt`,
`ParameterGrp.GetString`, `ParameterGrp.GetFloat`,
`ParameterGrp.GetBool`, or `ParameterGrp.GetUnsinged`.
References draftutils.utils.getParamType.
◆ get_param_type()
| def draftutils.utils.get_param_type | ( | param | ) |
Return the type of the parameter entered.
Parameters
----------
param : str
A string that indicates a parameter in the parameter database.
Returns
-------
str or None
The returned string could be `'int'`, `'string'`, `'float'`,
`'bool'`, `'unsigned'`, depending on the parameter.
It returns `None` for unhandled situations.
◆ get_real_name()
| def draftutils.utils.get_real_name | ( | name | ) |
Strip the trailing numbers from a string to get only the letters.
Parameters
----------
name : str
A string that may have a number at the end, `Line001`.
Returns
-------
str
A string without the numbers at the end, `Line`.
The returned string cannot be empty; it will have
at least one letter.
◆ get_rgb()
| def draftutils.utils.get_rgb | ( | color, | |
testbw = True |
|||
| ) |
Return an RRGGBB value #000000 from a FreeCAD color.
Parameters
----------
testwb : bool (default = True)
pure white will be converted into pure black
References draftutils.utils.getParam.
◆ get_type()
| def draftutils.utils.get_type | ( | obj | ) |
Return a string indicating the type of the given object.
Parameters
----------
obj : App::DocumentObject
Any type of scripted object created with Draft,
or any other workbench.
Returns
-------
str
If `obj` has a `Proxy`, it will return the value of `obj.Proxy.Type`.
* If `obj` is a `Part.Shape`, returns `'Shape'`
* If `'Sketcher::SketchObject'`, returns `'Sketch'`
* If `'Part::Line'`, returns `'Part::Line'`
* If `'Part::Offset2D'`, returns `'Offset2D'`
* If `'Part::Feature'`, returns `'Part'`
* If `'App::Annotation'`, returns `'Annotation'`
* If `'Mesh::Feature'`, returns `'Mesh'`
* If `'Points::Feature'`, returns `'Points'`
* If `'App::DocumentObjectGroup'`, returns `'Group'`
* If `'App::Part'`, returns `'App::Part'`
In other cases, it will return `'Unknown'`,
or `None` if `obj` is `None`.
Referenced by draftutils.utils.compare_objects(), and draftutils.utils.get_clone_base().
◆ get_windows()
| def draftutils.utils.get_windows | ( | obj | ) |
Return the windows and rebars inside a host.
Parameters
----------
obj : App::DocumentObject
A scripted object of type `'Wall'` or `'Structure'`
(Arch Workbench).
This will be searched for objects of type `'Window'` and `'Rebar'`,
and clones of them, and the found elements will be added
to the output list.
The function will search recursively all elements under `obj.OutList`,
in case the windows and rebars are nested under other walls
and structures.
Returns
-------
list
A list of all found windows and rebars in `obj`.
If `obj` is itself a `'Window'` or a `'Rebar'`, or a clone of them,
it will return the same `obj` element.
References draftutils.utils.getType, and draftutils.utils.isClone.
◆ is_clone()
| def draftutils.utils.is_clone | ( | obj, | |
| objtype, | |||
recursive = False |
|||
| ) |
Return True if the given object is a clone of a certain type.
A clone is of type `'Clone'`, and has a reference
to the original object inside its `Objects` attribute,
which is an `'App::PropertyLinkListGlobal'`.
The `Objects` attribute can point to another `'Clone'` object.
If `recursive` is `True`, the function will be called recursively
to further test this clone, until the type of the original object
can be compared to `objtype`.
Parameters
----------
obj : App::DocumentObject
The clone object that will be tested for a certain type.
objtype : str or list of str
A type string such as one obtained from `get_type`.
Or a list of such types.
recursive : bool, optional
It defaults to `False`.
If it is `True`, this same function will be called recursively
with `obj.Object[0]` as input.
This option only works if `obj.Object[0]` is of type `'Clone'`,
that is, if `obj` is a clone of a clone.
Returns
-------
bool
Returns `True` if `obj` is of type `'Clone'`,
and `obj.Object[0]` is of type `objtype`.
If `objtype` is a list, then `obj.Objects[0]`
will be tested against each of the elements in the list,
and it will return `True` if at least one element matches the type.
If `obj` isn't of type `'Clone'` but has the `CloneOf` attribute,
it will also return `True`.
It returns `False` otherwise, for example,
if `obj` is not even a clone.
References draftutils.utils.getType, and draftutils.utils.isClone.
◆ is_closed_edge()
| def draftutils.utils.is_closed_edge | ( | edge_index, | |
| object | |||
| ) |
◆ load_svg_patterns()
| def draftutils.utils.load_svg_patterns | ( | ) |
Load the default Draft SVG patterns and user defined patterns. The SVG patterns are added as a dictionary to the `App.svgpatterns` attribute.
References importSVG.getContents(), and draftutils.utils.getParam.
◆ precision()
| def draftutils.utils.precision | ( | ) |
Return the precision value from the parameter database.
It is the number of decimal places that a float will have.
Example
::
precision=6, 0.123456
precision=5, 0.12345
precision=4, 0.1234
Due to floating point operations there may be rounding errors.
Therefore, this precision number is used to round up values
so that all operations are consistent.
By default the precision is 6 decimal places.
Returns
-------
int
get_param("precision", 6)
References draftutils.utils.getParam.
◆ print_header()
| def draftutils.utils.print_header | ( | name, | |
| description, | |||
debug = True |
|||
| ) |
Print a line to the console when something is called, and log it.
Parameters
----------
name: str
The name of the function or class that is being called.
This `name` will be logged in the log file, so if there are problems
the log file can be investigated for clues.
description: str
Arbitrary text that will be printed to the console
when the function or class is called.
debug: bool, optional
It defaults to `True`.
If it is `False` the `description` will not be printed
to the console.
On the other hand the `name` will always be logged.
◆ print_shape()
| def draftutils.utils.print_shape | ( | shape | ) |
Print detailed information of a topological shape.
Parameters
----------
shape : Part::TopoShape
Any topological shape in an object, usually obtained from `obj.Shape`.
◆ set_param()
| def draftutils.utils.set_param | ( | param, | |
| value | |||
| ) |
Set a Draft parameter with the given value.
The parameter database is located in the tree
::
'User parameter:BaseApp/Preferences/Mod/Draft'
In the case that `param` is `'linewidth'` or `'color'` it will set
the View parameters
::
'User parameter:BaseApp/Preferences/View/DefaultShapeLineWidth'
'User parameter:BaseApp/Preferences/View/DefaultShapeLineColor'
Parameters
----------
param : str
A string that indicates a parameter in the parameter database.
value : int, or str, or float, or bool
The appropriate value of the parameter.
Depending on `param` and its type, determined with `get_param_type`,
it sets the appropriate value by calling `ParameterGrp.SetInt`,
`ParameterGrp.SetString`, `ParameterGrp.SetFloat`,
`ParameterGrp.SetBool`, or `ParameterGrp.SetUnsinged`.
References draftutils.utils.getParamType.
◆ shapify()
| def draftutils.utils.shapify | ( | obj | ) |
Transform a parametric object into a static, non-parametric shape.
Parameters
----------
obj : App::DocumentObject
Any type of scripted object.
This object will be removed, and a non-parametric object
with the same topological shape (`Part::TopoShape`)
will be created.
Returns
-------
Part::Feature
The new object that takes `obj.Shape` as its own.
Depending on the contents of the Shape, the resulting object
will be named `'Face'`, `'Solid'`, `'Compound'`,
`'Shell'`, `'Wire'`, `'Line'`, `'Circle'`,
or the name returned by `get_real_name(obj.Name)`.
If there is a problem with `obj.Shape`, it will return `None`,
and the original object will not be modified.
References draftutils.utils.getRealName.
◆ string_encode_coin()
| def draftutils.utils.string_encode_coin | ( | ustr | ) |
Encode a unicode object to be used as a string in coin.
Parameters
----------
ustr : str
A string to be encoded
Returns
-------
str
Encoded string. If the coin version is >= 4
it will encode the string to `'utf-8'`, otherwise
it will encode it to `'latin-1'`.
◆ svg_patterns()
| def draftutils.utils.svg_patterns | ( | ) |
Return a dictionary with installed SVG patterns.
Returns
-------
dict
Returns `App.svgpatterns` if it exists.
Otherwise it calls `load_svg_patterns` to create it
before returning it.
References draftutils.utils.loadSvgPatterns.
◆ tolerance()
| def draftutils.utils.tolerance | ( | ) |
Return the tolerance value from the parameter database.
This specifies a tolerance around a quantity.
::
value + tolerance
value - tolerance
By default the tolerance is 0.05.
Returns
-------
float
get_param("tolerance", 0.05)
References draftutils.utils.getParam.
Referenced by draftutils.utils.epsilon().
◆ type_check()
| def draftutils.utils.type_check | ( | args_and_types, | |
name = "?" |
|||
| ) |
Check that the arguments are instances of certain types.
Parameters
----------
args_and_types : list
A list of tuples. The first element of a tuple is tested as being
an instance of the second element.
::
args_and_types = [(a, Type), (b, Type2), ...]
Then
::
isinstance(a, Type)
isinstance(b, Type2)
A `Type` can also be a tuple of many types, in which case
the check is done for any of them.
::
args_and_types = [(a, (Type3, int, float)), ...]
isinstance(a, (Type3, int, float))
name : str, optional
Defaults to `'?'`. The name of the check.
Raises
------
TypeError
If the first element in the tuple is not an instance of the second
element, it raises `Draft.name`.
◆ ungroup()
| def draftutils.utils.ungroup | ( | obj | ) |
Remove the object from any group to which it belongs.
A "group" is any object returned by `get_group_names`.
Parameters
----------
obj : App::DocumentObject
Any type of scripted object.
References draftutils.utils.getGroupNames.
◆ use_instead()
| def draftutils.utils.use_instead | ( | function, | |
version = "" |
|||
| ) |
Print a deprecation message and suggest another function.
This function must be used inside the definition of a function
that has been considered for deprecation, so we must provide
an alternative.
::
def old_function():
use_instead('new_function', 1.0)
def someFunction():
use_instead('some_function')
Parameters
----------
function: str
The name of the function to use instead of the current one.
version: float or str, optional
It defaults to the empty string `''`.
The version where this command is to be deprecated, if it is known.
If we don't know when this command will be deprecated
then we should not give a version.
◆ utf8_decode()
| def draftutils.utils.utf8_decode | ( | text | ) |
Decode the input string and return a unicode string.
Python 2:
::
str -> unicode
unicode -> unicode
Python 3:
::
str -> str
bytes -> str
It runs
::
try:
return text.decode("utf-8")
except AttributeError:
return text
Parameters
----------
text : str, unicode or bytes
A str, unicode, or bytes object that may have unicode characters
like accented characters.
In Python 2, a `bytes` object can include accented characters,
but in Python 3 it must only contain ASCII literal characters.
Returns
-------
unicode or str
In Python 2 it will try decoding the `bytes` string
and return a `'utf-8'` decoded string.
>>> "Aá".decode("utf-8")
>>> b"Aá".decode("utf-8")
u'A\xe1'
In Python 2 the unicode string is prefixed with `u`,
and unicode characters are replaced by their two-digit hexadecimal
representation, or four digit unicode escape.
>>> "AáBẃCñ".decode("utf-8")
u'A\xe1B\u1e83C\xf1'
In Python 2 it will always return a `unicode` object.
In Python 3 a regular string is already unicode encoded,
so strings have no `decode` method. In this case, `text`
will be returned as is.
In Python 3, if `text` is a `bytes` object, then it will be converted
to `str`; in this case, the `bytes` object cannot have accents,
it must only contain ASCII literal characters.
>>> b"ABC".decode("utf-8")
'ABC'
In Python 3 it will always return a `str` object, with no prefix.
Variable Documentation
◆ ARROW_TYPES
| list draftutils.utils.ARROW_TYPES = ["Dot", "Circle", "Arrow", "Tick", "Tick-2"] |
◆ arrowtypes
| list draftutils.utils.arrowtypes = ARROW_TYPES |
◆ compareObjects
| def draftutils.utils.compareObjects = compare_objects |
◆ convertDraftTexts
| def draftutils.utils.convertDraftTexts = convert_draft_texts |
◆ filterObjectsForModifiers
| def draftutils.utils.filterObjectsForModifiers = filter_objects_for_modifiers |
◆ getCloneBase
| def draftutils.utils.getCloneBase = get_clone_base |
◆ getDXF
| def draftutils.utils.getDXF = get_DXF |
Referenced by draftutils.utils.get_DXF().
◆ getGroupContents
| def draftutils.utils.getGroupContents = get_group_contents |
Referenced by draftutils.utils.get_group_contents().
◆ getGroupNames
| def draftutils.utils.getGroupNames = get_group_names |
Referenced by draftutils.utils.ungroup().
◆ getMovableChildren
| def draftutils.utils.getMovableChildren = get_movable_children |
Referenced by draftutils.utils.get_movable_children().
◆ getObjectsOfType
| def draftutils.utils.getObjectsOfType = get_objects_of_type |
◆ getParam
| def draftutils.utils.getParam = get_param |
◆ getParamType
| def draftutils.utils.getParamType = get_param_type |
Referenced by draftutils.utils.get_param(), and draftutils.utils.set_param().
◆ getRealName
| def draftutils.utils.getRealName = get_real_name |
Referenced by draftutils.utils.shapify().
◆ getrgb
| def draftutils.utils.getrgb = get_rgb |
◆ getType
| def draftutils.utils.getType = get_type |
◆ getWindows
| def draftutils.utils.getWindows = get_windows |
Referenced by draftutils.utils.get_group_contents().
◆ isClone
| def draftutils.utils.isClone = is_clone |
Referenced by draftutils.utils.get_windows(), and draftutils.utils.is_clone().
◆ isClosedEdge
| def draftutils.utils.isClosedEdge = is_closed_edge |
◆ loadSvgPatterns
| def draftutils.utils.loadSvgPatterns = load_svg_patterns |
Referenced by draftutils.utils.svg_patterns().
◆ printShape
| def draftutils.utils.printShape = print_shape |
◆ setParam
| def draftutils.utils.setParam = set_param |
◆ stringencodecoin
| def draftutils.utils.stringencodecoin = string_encode_coin |
◆ svgpatterns
| def draftutils.utils.svgpatterns = svg_patterns |
◆ typecheck
| def draftutils.utils.typecheck = type_check |
