Object name

Other languages:

Introduction

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.

Names

There are various properties for Names:

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.

Labels

There are various properties for Labels: 

<<Custom Label With Spaces>>.Height
<<Label may use UTF8 characters>>.Width

Label2

It is a simple string that can contain arbitrary text, and therefore can be used for documenting (describing with more detail) the created object.

Scripting

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"

Name

The addObject function has two basic string arguments.

Label

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

Getting an object by Name or Label

All objects in a document are data attributes of the corresponding Document object. The attribute's name correspond to the internal Name of the object. 

import FreeCAD as App

obj1 = App.ActiveDocument.Box
obj2 = App.ActiveDocument.Box001
obj3 = App.ActiveDocument.Box002

This is equivalent to using the getObject method of the Document. 

import FreeCAD as App

obj1 = App.ActiveDocument.getObject('Box')
obj2 = App.ActiveDocument.getObject('Box001')
obj3 = App.ActiveDocument.getObject('Box002')

However, it is also possible to get the object by the more descriptive Label. 

import FreeCAD as App

obj1 = App.ActiveDocument.getObjectsByLabel("Concrete wall")[0]
obj2 = App.ActiveDocument.getObjectsByLabel("Custom parallelepiped")[0]
obj3 = App.ActiveDocument.getObjectsByLabel("Some special name for this cube__002")[0]

Given that the Label is in general not unique, the getObjectsByLabel method returns a list with all objects found with that Label. However, if the Label is unique in the document then the first element in that list should be the desired object.

User documentation