Skip to content

Editing Items#

Items are edited via the attributes they define which are managed and modified using the Attribute Editor. Generally speaking, each time an item is modified, there is always at least one of its attributes that has been modified. In Clarisse, it's very simple and editing attribute values is the only way to modify items:

  • To translate a selected Scene Item, the Translate tool modifies the item's Translate attribute.
  • When assigning a material to a geometry via a drag and drop, the Materials attribute of the geometry is modified.
  • Parenting a light to a geometry is achieved by setting the Parent attribute of the geometry to the light.

What are attributes?#

Attributes are modifiable properties of items. They are defined by a name, a type, flags, modifiers and a category where:

  • name identifies the attribute
  • type defines the value type (string, integer, floating point, reference, script...)
  • flags define the behavior of the attribute such as its visibility or its state (editable/read-only...)
  • modifiers are Textures or FCurves, expressions... modifying the final attribute value
  • category defines a hint used to logically sort attributes of an item in the user interface

Attribute Name#

Attribute names identify attributes on items which share the same the limitations as item names:

  • names can't start with a digit
  • names support only underscores and alphanumeric characters

To circumvent these limitations, displayed names are automatically converted to a more human readable format.

For example, the attribute enable_subdivision_surface is displayed as Enable Subdivision Surface in the User Interface. To get the technical name of an attribute, look at the technical reference documentation. Search for the module class and select the Technical tab to display the technical documentation of the module.

Note

Since Attribute names are used to identify attributes, the attribute names are always unique for an item.

Attribute Type#

Attributes types define the attribute value type. There are many types of attribute values and each one is displayed differently throughout the application. Attributes can be composed of single or multiple values in which case they are either displayed as a list or a successive block of values.

Attribute type can also be of type Object. In this case, objects are embedded by the attribute. Embedded objects are owned by and bundled with their parent object. They can't be connected by anything other than their owners. For example, the list of layers of an image is a list referencing embedded objects.

Attribute Flags#

Flags define the attribute properties such as their visibility and more. Attributes can be public (default), private or read-only. Public attributes are freely modifiable by users whereas private attributes are hidden and unavailable to the user. They are generally used by the engine associated to the item. Read-only attributes on the other hand are displayed but can't be modified by the user.

Note

Read-only state isn't necessarily permanent. Depending on user actions, the read-only flag state of an attribute can be removed. For example on Polymesh objects, if Enable Suddivision Surface is unchecked, all subdivision surface related attributes are flagged as read-only. However, if the attribute is checked, they lose their read-only state.

Attribute Protection#

Attributes can be in a protected state. A protected attribute is an attribute of an item currently in use by a running evaluation. In other words, an attribute can only be protected if a running evaluation depends on an item that owns the attribute.

For example, when the orbiting a camera connected to a layer scene of an image currently being evaluated. Since the evaluation depends on the item, the transform attributes are projected. Modifying these attributes ultimately leads to the interruption and the restart of the running evaluation.

Attribute Modifiers#

Attribute modifiers are operators that modify the value of an attribute. There are several kinds of attribute modifiers. While attributes can have multiple modifiers at the same time, only a single modifier is evaluated following this the priority defined below (highest to lowest):

Priority Modifier
1 Shading Variable
2 Texture
3 Expression
4 FCurve
5 Attribute Value
6 Attribute Source (can be textured, animated...)

If an attribute has a shading variable, the attribute is only driven by the shading variable, even if the attribute has other kinds of modifiers. When an attribute has both a texture and a F-Curve, the attribute is driven by the texture.

Disabling Attributes#

Disabling an attribute results in ignoring the current attribute value. It behaves as if the value is restored to its default value which is the value of the attribute when the item is created. The disable action is a toggle. It doesn't reset the attribute to the default value.

At any time you can re-enable back the attribute to take into account its actual value. Disabled attributes are displayed as strikethrough in the Attribute Editor.

Note

When an attribute is disabled, it is set as read-only. It can't be edited.

Disabling Reference Value#

Disabling a reference value is toggle that allows Clarisse to act as if an item wasn't being physically connected by the attribute. For example, if an attribute Parent is referencing the object project://scene/light when the attribute Parent is disabled the the item acts as if its value was set to (none).

Muting Local Attribute Value#

Muting the local value of an attribute disables the attribute as if it wasn't localized. When the attribute of an instance is muted it returns the value of its immediate source. For items that are not instances, muted attributes return the default value of the item. In that case muting the attribute is equivalent to disabling the attribute. Please note that when an attribute is muted it can' t be edited and it is displayed as read-only.

Locking Attributes#

It is possible to lock individual attributes to prevent further edition by users.

Per Value Locks#

Instead of locking the attribute completely, it is possible to lock individual attribute values for attributes of type array. For example, it is possible to lock only the Y axis of the Translate attribute of a scene item. This way the user won't be able to move the item in the Y axis.

Attribute Group#

The attribute group logically sorts attributes into groups when displayed in the Attribute Editor. For example, Translate and Rotate attributes share the same category Kinematics so they are then displayed in the same group.

Note

When an attribute has no category defined, it is considered as member of an implicit category named General.

Creating Custom Attributes#

It is possible to add custom attributes to items using the Attribute Editor or via scripting. For more information about how to create custom attributes using the Attribute Editor please refer to Attribute Editor.

ix.selection[0].add_attribute("my_custom_attribute", ix.api.OfAttr.TYPE_BOOL)

This adds to the selected object a new attribute of type bool called my_custom_attribute. For more information please refer to the SDK/API reference. Custom attributes are saved in the project/build file.

Here is how looks the serialization of a custom attribute on a Locator.

Locator {
 name "locator"
 custom_attributes {
   bool "my_custom_attribute" {
     value no
   }
 }
}