Data Structures

Data Structures #

Despite the new operators, this add-on prefers an unobtrusive style that does not change the original way that Blender's objects work. However, some operators must create new properties/attributes in an object to store additional information. This pages list all new data structures created by the add-on.

Add-On Registering #

All add-on operators are registered under bpy.ops.gpencil with the name prefix nijigp_. The add-on chooses gpencil as the category instead of creating a new one, because this allows users to assign shortcut to each operator.

The add-on stores global setting options by defining properties with the name prefix nijigp_ in bpy.types.Scene.

Custom Properties #

Materials #

  • original_material_index: Operators such as Hole Holdout may generate new materials from existing ones. The new material uses this property to mark the material slot number of the original material.

Objects #

Mesh objects generated by this add-on from Grease Pencil strokes have following properties defined:

  • nijigp_mesh: The type of the mesh. Currently, it can be either planar or 3d.

  • nijigp_parent: A pointer to the Grease Pencil object that generates this mesh.

    • The parentship needs to be stored in this way persistently, because Rigging Operators may change the parentship of involved objects.

Mesh Attributes #

Meshes generated by this add-on use attributes for shaders and Geometry Nodes. Besides the regular attributes like Color and UVMap, there are also new ones defined:

  • NormalMap: The normal vector calculated by the Normal Interpolation operator.

  • Depth: A Float representing the height/depth of each vertex, normalized to 0~1 range.

    • This value is deduced from the normal vector, which may not be the same with actual vertex coordinate.
    • Currently, none of the default shaders uses this attribute. However, the user can create their own shaders with it.

  • start_frame, end_frame: Integers marking the frame range of the stroke generating this mesh. The Stop-Motion Animation option will insert a Geometry Nodes group to show/hide the mesh according to these values.

All of these new attributes are vertex attributes.

Grease Pencil 3.0 #

This add-on was primarily developed for Blender 3.3 ~ 4.2 with Grease Pencil 2 (GPv2). In Blender 4.3 the Grease Pencil module is completely rewritten as 3.0 (GPv3), using a completely different set of Python APIs without backwards compatibility.

To maintain the functionality of the add-on for both GPv2 and GPv3, a module api_router.py is used to provide a compatibility layer. It has two main tasks:

  • Some keywords/attributes/operators have different names but similar functions in GPv2 and GPv3. The compatibility layer will choose the correct name to call depending on the version of Blender.
  • Some important APIs, including Stroke and its collection, as well as StrokePoint and its collection work in distinct ways in GPv3, which break the add-on operators. These GPv3 APIs are no longer used by the add-on. Instead, a set of equivalent APIs are developed that emulate the behavior of the GPv2 APIs using GPv3 data. This allows the other add-on modules to manipulate strokes and points without being aware of the Blender version most of the time.

The emulation approach is possible because GPv3 supports defining custom attributes that can be used in Geometry Nodes. To make the emulated APIs as capable as GPv2, the add-on defines several new attributes named .nijigp_*:

  • .nijigp_hash: A random large integer assigned to each stroke as a unique identifier, making each stroke persistently traceable even if its index changes.
  • .nijigp_new: A boolean value indicating whether a newly created stroke has not been configured. In GPv2, a new stroke has no points. However, a GPv3 stroke comes with a point when created. This attribute works as a reminder that the first point has not been configured.
  • .nijigp_weight_proxy_%d: A number value for each point. Currently, GPv3 has difficulty accessing the vertex weights via Python. The emulator API accesses this attribute instead, and then copies the value to the actual weight via Geometry Nodes. This workflow may be improved in the future.