Object name

From FreeCAD Documentation
Revision as of 10:29, 3 June 2020 by Renatorivo (talk | contribs) (Marked this version for translation)
Jump to navigation Jump to search
Other languages:
Deutsch • ‎English • ‎français


All objects in the program have an object name that uniquely identifies them in a given Document.

This information applies to all objects derived from App DocumentObject (App::DocumentObject class), which essentially comprises all objects that are possible to create in a document.


There are various properties for Names:

  • The Name can only include simple alphanumeric characters, and the underscore, [_0-9a-zA-Z].
  • The Name cannot start with a number; it must start with a letter or the underscore, [_a-zA-Z].
  • The Name is assigned at the creation time of the object; afterwards it is no longer editable. The object can never be renamed.
  • The Name must be unique in the entire document. It doesn't matter if two objects are of completely different types, for example, one is a PartDesign Pocket and the other is an Arch Wall. They must have different names.
  • When creating an object of the same type, normally the name is increased with a sequential number, thus Box, Box001, Box002, etc. This prevents naming collision.
  • Once the object is deleted, its Name becomes available to be used by a newly created object. This means that if Box, Box001, and Box002 exist, and we delete the first item, the next box created with Part Box will not be Box003, it will be Box again, because this string is available to be used once more. Notice that it is not possible to rename Box001 or Box002 to Box since their names are fixed.

In summary, the Name essentially acts like a unique identifier (UID) for an object. Since a unique Name is very restrictive, all objects also have a Label property which allows "renaming" the object to something more descriptive. The internal Name actually remains fixed, but the user editable Label can be used in most situations where the Name would be used. In common usage in the program and the documentation, "renaming" means changing the Label and not the actual Name of the object.


There are various properties for Labels:

  • The Label can accept any UTF8 string, including accents and spaces.
  • The tree view actually displays the Label of the object, not the Name. Therefore, whenever a new object is created, it is a good practice to change the Label to a more descriptive string. To rename (relabel) the object, select it in the tree view and press F2, or open the context menu (right-click) and choose Rename.
  • Even after an object was renamed (relabelled), the internal Name will still be reported in many places, for example, in the status bar or in the selection view, when the object is selected.
  • Since the internal functions of the program refer to the objects by Name, many dialogs will display the Name first, followed by the user editable Label in parentheses, for example, Box (Extruded piece).
  • By default the Label is unique, just like the Name. However, this behavior can be changed in the preferences editor, Edit → Preferences → General → Document → Allow duplicate object labels in one document. This means that in general the Label is not unique in the document, and may actually be repeated. However, the recommendation is to keep the Label unique, as this is probably what is most useful to identify different objects. When writing custom functions that manipulate objects, the methods should use the Name of the object rather than its Label to guarantee that the correct object is used.


See also: FreeCAD Scripting Basics, and scripted objects.

Any object in the software is internally created with the addObject() method of the document. The majority of 2D and 3D objects that the user will see in the 3D view are derived from a Part Feature. In the following example, the object created is a Part Box.

import FreeCAD as App

doc = App.newDocument()
obj = doc.addObject("Part::Box", "Name")
obj.Label = "Custom label"


The addObject function has two basic string arguments.

  • The first argument indicates the type of object, in this case, "Part::Box".
  • The second argument is a string that defines the Name attribute. If it is not provided, it defaults to the same name as the class of the object, that is, "Part__Box", where the two invalid symbols, the colons ::, are replaced by two underscores __.
    • The Name can only include simple alphanumeric characters, and the underscore, [_0-9a-zA-Z]. If other symbols are given, these will be converted to underscores; for example, "A+B:C*" is converted to "A_B_C_".
    • The Name cannot start with a number; it must start with a letter or the underscore, [_a-zA-Z]. For example, "123ABC" is converted to "_23ABC".
    • The Name is fixed at creation time; it cannot be modified afterwards.
    • The Name must be unique in the entire document. If the same "Name" is used, a sequential number will be appended automatically so that the resulting names are unique; for example, if "Name" already exists, then new objects will be called "Name001", "Name002", "Name003", etc.


The Label is a property of the created object and can be changed to a more meaningful text.

  • Upon creating the object, the Label is the same as the Name.
  • However, unlike the Name, the Label can accept any UTF8 string, including accents and spaces.
  • The Label can be changed at any point in time just by assigning the desired string, obj.Label = "New label"