Draft Label

From FreeCAD Documentation
Revision as of 19:45, 28 March 2021 by Roy 043 (talk | contribs)
This documentation is a work in progress. Please don't mark it as translatable since it will change in the next hours and days.

Draft Label

Menu location
Annotation → Label
Workbenches
Draft, Arch
Default shortcut
D L
Introduced in version
0.17
See also
Draft Text, Draft ShapeString

Description

The Draft Label command inserts a multi-line textbox with a 2-segment leader line and an arrow. If an object or a sub-element (face, edge or vertex) is selected when starting the command, the Label can be made to display a certain attribute of the selected element, including position, length, area, volume, or material.

To insert a text element without an arrow use the Draft Text command.

Various labels with different orientations, tip symbols, and information

Usage

  1. There are several ways to invoke the command:
    • Press the Draft Label button.
    • Select the Annotation → Label option from the menu.
    • Use the keyboard shortcut: D then L.
  2. Click the first point in the 3D view, or type coordinates and press the Enter point button. This point indicates the target (arrow head). This can be anywhere, it doesn't have to be an element.
  3. Click the second point in the 3D view, or type coordinates and press the Enter point button. This point indicates the start of a horizontal or vertical leader.
  4. Click the third point in the 3D view, or type coordinates and press the Enter point button. This point indicates the base point of the text.

Options

  • Click on Label type to select the type of information to display, including "Custom", "Name", "Label", "Position", "Length", "Area", "Volume", "Tag", and "Material". (See explanation of Label types below)
  • To enter coordinates manually, simply enter the numbers, then press Enter between each X, Y and Z component. You can press the Enter point button when you have the desired values to insert the point.
  • Hold Ctrl while placing the label to force snapping your point to the nearest snap location, independently of the distance.
  • Press Esc or the Close button to abort the current command.

Notes

  • The direction of the horizontal straight segment, to the right or to the left, will automatically align the text to the opposite direction. If the leader goes vertically up, the text is aligned to the left. If it goes vertically down, it is aligned to the right.
  • By pre-selecting an object, or a sub-element (vertex, edge or face), before pressing the command button, the label will become parametric, that is, it will remember which object it is bound to, and it will be able to display a particular attribute of that object. If the attributes of the object change later on, the label will adjust the displayed information.

Properties

See also: Property editor.

A Draft Label object is derived from an App FeaturePython object and inherits all its properties. The following properties are additional unless otherwise stated:

Data

Label

  • DataCustom Text (StringList): specifies the contents of the text if DataLabel Type is Custom. Each item in the list represents a new text line.
  • DataLabel Type (Enumeration): specifies the type of information displayed by the label (see Label types below).
  • DataPlacement (Placement): specifies the position of the text in the 3D view and, unless DataStraight Direction is Custom, also of the first leader segment, which is the segment where the text is attached. See Placement.
  • DataText (StringList): (read-only) specifies the contents of the text that is actually displayed. Each item in the list represents a new text line.

Leader

  • DataPoints (VectorList): specifies the points of the leader.
  • DataStraight Direction (Enumeration): specifies the direction of the first leader segment: Custom, Horizontal or Vertical.
  • DataStraight Distance (Distance): specifies the length of the first leader segment. If the distance is positive, the leader starts from the right side of the text, and the text aligns to the right. Otherwise the leader starts from the left side of the text, and the text aligns to the left.

Target

  • DataTarget (LinkSub): specifies the object and optional subelement the label is linked to.
  • DataTarget Point (Vector): specifies the position of the end point of the leader, which is where the arrow is attached.

Label types

  • Custom: displays the contents of DataCustom Text.
  • Name: displays the internal name of the target object. The internal name is assigned when an object is created, and remains fixed throughout the existence of the object.
  • Label: displays the label of the target object. The label of an object can be changed by the user.
  • Position: displays the coordinates of the base point of the target object, of the target vertex, or of the center of mass of the target subelement, if applicable.
  • Length: displays the length of the target object or subelement, if applicable.
  • Area: displays the area of the target object or subelement, if applicable.
  • Volume: displays the volume of the target object, if applicable.
  • Tag: displays the Tag attribute of the target object, if applicable. Objects created with the Arch Workbench can have this attribute.
  • Material: displays the name of the material of the target object, if applicable.
  • Label + Position
  • Label + Length
  • Label + Area
  • Label + Volume
  • Label + Material

View

Annotation

  • ViewAnnotation Style (Enumeration): specifies the annotation style applied to the label. See Draft AnnotationStyleEditor.
  • ViewScale Multiplier (Float): specifies the general scaling factor applied to the label.

Display Options

  • ViewDisplay Mode: if it is "3D text" the text will be aligned to the scene axes, initially lying on the XY plane; if it is "2D text" the text will always face the camera.

Graphics

  • ViewArrow Size (Length): specifies the size of the symbol displayed at the tip of the leader.
  • ViewArrow Type (Enumeration): specifies the type of symbol displayed at the tip of the leader, which can be dot, circle, arrow, or tick.
  • ViewFrame (Enumeration): if it is "Rectangle" it will draw a frame around the text.
  • ViewLine (Bool): if it is true the leader line will be displayed; otherwise only the text and the symbol at the tip will be displayed.
  • ViewLine Color (Color): specifies the color of the leader.
  • ViewLine Width (Float): specifies the width of the leader

Text

  • ViewJustification (Enumeration): specifies if the alignment of the text: left, right, or center.
  • ViewLine Spacing (Float): specifies the factor applied to the default line height of the text.
  • ViewMax Chars (Integer)
  • ViewText Alignment (Enumeration): specifies the vertical alignment of the baseline of the text with respect to the leader. It can be top, middle or bottom.
  • ViewText Color (Color): specifies the color of the text in an RGB tuple (R, G, B).
  • ViewText Font (Font): specifies the font to use to draw the text. It can be a font name, such as "Arial", a default style such as "sans", "serif" or "mono", a family such as "Arial,Helvetica,sans" or a name with a style such as "Arial:Bold". If the given font is not found on the system, a generic one is used instead.
  • ViewText Size (Length): specifies the size of the text. If the label object is created in the tree view but no text is visible in the 3D view, increase the size of the text until it is visible.

Scripting

See also: Autogenerated API documentation and FreeCAD Scripting Basics.

To create a Draft Label use the make_label method (introduced in version 0.19) of the Draft module. This method replaces the deprecated makeLabel method.

label = 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)

Example:

import FreeCAD as App
import Draft

rectangle = Draft.make_rectangle(4000, 1000)
App.ActiveDocument.recompute()

p1 = App.Vector(-200, 1000, 0)
place1 = App.Placement(App.Vector(-1000, 1300, 0), App.Rotation())

label1 = Draft.make_label(p1, place1, target_object=rectangle, distance=500, label_type="Label")
label1.ViewObject.TextSize = 200

p2 = App.Vector(-200, 0, 0)
place2 = App.Placement(App.Vector(-1000, -300, 0), App.Rotation())

label2 = Draft.make_label(p2, place2, target_object=rectangle, distance=500, label_type="Custom",
                          custom_text="Beware of the sharp edges")
label2.ViewObject.TextSize = 200

p3 = App.Vector(1000, 1200, 0)
place3 = App.Placement(App.Vector(2000, 1800, 0), App.Rotation())

label3 = Draft.make_label(p3, place3, target_object=rectangle, distance=-500, label_type="Area")
label3.ViewObject.TextSize = 200

App.ActiveDocument.recompute()