def make_label(targetpoint=None, target=None, direction=None,
distance=None, labeltype=None, placement=None):
"""
make_label(targetpoint, target, direction, distance, labeltype, placement)
Function to create a Draft Label annotation object
Parameters
----------
targetpoint : App::Vector
To be completed
target : LinkSub
To be completed
direction : String
Straight direction of the label
["Horizontal","Vertical","Custom"]
distance : Quantity
Length of the straight segment of label leader line
labeltype : String
Label type in
["Custom","Name","Label","Position",
"Length","Area","Volume","Tag","Material"]
placement : Base::Placement
To be completed
Returns
-------
obj : App::DocumentObject
Newly created label object
"""
obj = App.ActiveDocument.addObject("App::FeaturePython",
"dLabel")
Label(obj)
if App.GuiUp:
ViewProviderLabel(obj.ViewObject)
if targetpoint:
obj.TargetPoint = targetpoint
if target:
obj.Target = target
if direction:
obj.StraightDirection = direction
if distance:
obj.StraightDistance = distance
if labeltype:
obj.LabelType = labeltype
if placement:
obj.Placement = placement
if App.GuiUp:
gui_utils.format_object(obj)
gui_utils.select(obj)
return obj
def make_label(target_point=App.Vector(0, 0, 0),
placement=App.Vector(30, 30, 0),
target_object=None, subelements=None,
label_type="Custom", custom_text="Label",
direction="Horizontal", distance=-10,
points=None):
"""Create a Label object containing different types of information.
The current color and text height and font specified in preferences
are used.
Parameters
----------
target_point: Base::Vector3, optional
It defaults to the origin `App.Vector(0, 0, 0)`.
This is the point which is pointed to by the label's leader line.
This point can be adorned with a marker like an arrow or circle.
placement: Base::Placement, Base::Vector3, or Base::Rotation, optional
It defaults to `App.Vector(30, 30, 0)`.
If it is provided, it defines the base point of the textual
label.
The input could be a full placement, just a vector indicating
the translation, or just a rotation.
target_object: Part::Feature or str, optional
It defaults to `None`.
If it exists it should be an object which will be used to provide
information to the label, as long as `label_type` is different
from `'Custom'`.
If it is a string, it must be the `Label` of that object.
Since a `Label` is not guaranteed to be unique in a document,
it will use the first object found with this `Label`.
subelements: str, optional
It defaults to `None`.
If `subelements` is provided, `target_object` should be provided
as well, otherwise it is ignored.
It should be a string indicating a subelement name, either
`'VertexN'`, `'EdgeN'`, or `'FaceN'` which should exist
within `target_object`.
In this case `'N'` is an integer that indicates the specific number
of vertex, edge, or face in `target_object`.
Both `target_object` and `subelements` are used to link the label
to a particular object, or to the particular vertex, edge, or face,
and get information from them.
::
make_label(..., target_object=App.ActiveDocument.Box)
make_label(..., target_object="My box", subelements="Face3")
These two parameters can be can be obtained from the `Gui::Selection`
module.
::
sel_object = Gui.Selection.getSelectionEx()[0]
target_object = sel_object.Object
subelements = sel_object.SubElementNames[0]
label_type: str, optional
It defaults to `'Custom'`.
It can be `'Custom'`, `'Name'`, `'Label'`, `'Position'`,
`'Length'`, `'Area'`, `'Volume'`, `'Tag'`, or `'Material'`.
It indicates the type of information that will be shown in the label.
Only `'Custom'` allows you to manually set the text
by defining `custom_text`. The other types take their information
from the object included in `target`.
- `'Position'` will show the base position of the target object,
or of the indicated `'VertexN'` in `target`.
- `'Length'` will show the `Length` of the target object's `Shape`,
or of the indicated `'EdgeN'` in `target`.
- `'Area'` will show the `Area` of the target object's `Shape`,
or of the indicated `'FaceN'` in `target`.
custom_text: str, optional
It defaults to `'Label'`.
It is the text that will be displayed by the label when
`label_type` is `'Custom'`.
direction: str, optional
It defaults to `'Horizontal'`.
It can be `'Horizontal'`, `'Vertical'`, or `'Custom'`.
It indicates the direction of the straight segment of the leader line
that ends up next to the textual label.
If `'Custom'` is selected, the leader line can be manually drawn
by specifying the value of `points`.
Normally, the leader line has only three points, but with `'Custom'`
you can specify as many points as needed.
distance: int, float, Base::Quantity, optional
It defaults to -10.
It indicates the length of the horizontal or vertical segment
of the leader line.
The leader line is composed of two segments, the first segment is
inclined, while the second segment is either horizontal or vertical
depending on the value of `direction`.
::
T
|
|
o------- L text
The `oL` segment's length is defined by `distance`
while the `oT` segment is automatically calculated depending
on the values of `placement` (L) and `distance` (o).
This `distance` is oriented, meaning that if it is positive
the segment will be to the right and above of the textual
label, depending on if `direction` is `'Horizontal'` or `'Vertical'`,
respectively.
If it is negative, the segment will be to the left
and below of the text.
points: list of Base::Vector3, optional
It defaults to `None`.
It is a list of vectors defining the shape of the leader line;
the list must have at least two points.
This argument must be used together with `direction='Custom'`
to display this custom leader.
However, notice that if the Label's `StraightDirection` property
is later changed to `'Horizontal'` or `'Vertical'`,
the custom point list will be overwritten with a new,
automatically calculated three-point list.
For the object to use custom points, `StraightDirection`
must remain `'Custom'`, and then the `Points` property
can be overwritten by a suitable list of points.
Returns
-------
App::FeaturePython
A scripted object of type `'Label'`.
This object does not have a `Shape` attribute, as the text and lines
are created on screen by Coin (pivy).
None
If there is a problem it will return `None`.
"""
_name = "make_label"
utils.print_header(_name, "Label")
found, doc = utils.find_doc(App.activeDocument())
if not found:
_err(_tr("No active document. Aborting."))
return None
_msg("target_point: {}".format(target_point))
if not target_point:
target_point = App.Vector(0, 0, 0)
try:
utils.type_check([(target_point, App.Vector)], name=_name)
except TypeError:
_err(_tr("Wrong input: must be a vector."))
return None
_msg("placement: {}".format(placement))
if not placement:
placement = App.Placement()
try:
utils.type_check([(placement, (App.Placement,
App.Vector,
App.Rotation))], name=_name)
except TypeError:
_err(_tr("Wrong input: must be a placement, a vector, "
"or a rotation."))
return None
# Convert the vector or rotation to a full placement
if isinstance(placement, App.Vector):
placement = App.Placement(placement, App.Rotation())
elif isinstance(placement, App.Rotation):
placement = App.Placement(App.Vector(), placement)
if isinstance(target_object, str):
target_object_str = target_object
if target_object:
if isinstance(target_object, (list, tuple)):
_msg("target_object: {}".format(target_object))
_err(_tr("Wrong input: object must not be a list."))
return None
found, target_object = utils.find_object(target_object, doc)
if not found:
_msg("target_object: {}".format(target_object_str))
_err(_tr("Wrong input: object not in document."))
return None
_msg("target_object: {}".format(target_object.Label))
if target_object and subelements:
_msg("subelements: {}".format(subelements))
try:
# Make a list
if isinstance(subelements, str):
subelements = [subelements]
utils.type_check([(subelements, (list, tuple, str))],
name=_name)
except TypeError:
_err(_tr("Wrong input: must be a list or tuple of strings. "
"Or a single string."))
return None
# The subelements list is used to build a special list
# called a LinkSub, which includes the target_object
# and the subelements.
# Single: (target_object, "Edge1")
# Multiple: (target_object, ("Edge1", "Edge2"))
for sub in subelements:
_sub = target_object.getSubObject(sub)
if not _sub:
_err("subelement: {}".format(sub))
_err(_tr("Wrong input: subelement not in object."))
return None
_msg("label_type: {}".format(label_type))
if not label_type:
label_type = "Custom"
try:
utils.type_check([(label_type, str)], name=_name)
except TypeError:
_err(_tr("Wrong input: must be a string, "
"'Custom', 'Name', 'Label', 'Position', "
"'Length', 'Area', 'Volume', 'Tag', or 'Material'."))
return None
if label_type not in ("Custom", "Name", "Label", "Position",
"Length", "Area", "Volume", "Tag", "Material"):
_err(_tr("Wrong input: must be a string, "
"'Custom', 'Name', 'Label', 'Position', "
"'Length', 'Area', 'Volume', 'Tag', or 'Material'."))
return None
_msg("custom_text: {}".format(custom_text))
if not custom_text:
custom_text = "Label"
try:
utils.type_check([(custom_text, str)], name=_name)
except TypeError:
_err(_tr("Wrong input: must be a string."))
return None
_msg("direction: {}".format(direction))
if not direction:
direction = "Horizontal"
try:
utils.type_check([(direction, str)], name=_name)
except TypeError:
_err(_tr("Wrong input: must be a string, "
"'Horizontal', 'Vertical', or 'Custom'."))
return None
if direction not in ("Horizontal", "Vertical", "Custom"):
_err(_tr("Wrong input: must be a string, "
"'Horizontal', 'Vertical', or 'Custom'."))
return None
_msg("distance: {}".format(distance))
if not distance:
distance = 1
try:
utils.type_check([(distance, (int, float))], name=_name)
except TypeError:
_err(_tr("Wrong input: must be a number."))
return None
if points:
_msg("points: {}".format(points))
_err_msg = _tr("Wrong input: must be a list of at least two vectors.")
try:
utils.type_check([(points, (tuple, list))], name=_name)
except TypeError:
_err(_err_msg)
return None
if len(points) < 2:
_err(_err_msg)
return None
if not all(isinstance(p, App.Vector) for p in points):
_err(_err_msg)
return None
new_obj = doc.addObject("App::FeaturePython",
"dLabel")
Label(new_obj)
new_obj.TargetPoint = target_point
new_obj.Placement = placement
if target_object:
if subelements:
new_obj.Target = [target_object, subelements]
else:
new_obj.Target = [target_object, []]
new_obj.LabelType = label_type
new_obj.CustomText = custom_text
new_obj.StraightDirection = direction
new_obj.StraightDistance = distance
if points:
if direction != "Custom":
_wrn(_tr("Direction is not 'Custom'; "
"points won't be used."))
new_obj.Points = points
if App.GuiUp:
ViewProviderLabel(new_obj.ViewObject)
h = utils.get_param("textheight", 0.20)
new_obj.ViewObject.TextSize = h
gui_utils.format_object(new_obj)
gui_utils.select(new_obj)
return new_obj