user: How do I use GreasePencil(ID) in Blender? Include parameters, examples, warnings and best practices.

assistant: # GreasePencil(ID)

base classes — [`bpy_struct`](bpy.types.bpy_struct.html#bpy.types.bpy_struct "bpy.types.bpy_struct"), [`ID`](bpy.types.ID.html#bpy.types.ID "bpy.types.ID")

*class* bpy.types.GreasePencil(*ID*)
:   Grease Pencil data-block

    after_color
    :   Base color for ghosts after the active frame

        Type:
        :   [`mathutils.Color`](mathutils.html#mathutils.Color "mathutils.Color") of 3 items in [0, 1], default (0.12549, 0.082353, 0.529412)

    animation_data
    :   Animation data for this data-block

        Type:
        :   [`AnimData`](bpy.types.AnimData.html#bpy.types.AnimData "bpy.types.AnimData"), (readonly)

    attributes
    :   Geometry attributes

        Type:
        :   [`AttributeGroupGreasePencil`](bpy.types.AttributeGroupGreasePencil.html#bpy.types.AttributeGroupGreasePencil "bpy.types.AttributeGroupGreasePencil") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`Attribute`](bpy.types.Attribute.html#bpy.types.Attribute "bpy.types.Attribute"), (readonly)

    before_color
    :   Base color for ghosts before the active frame

        Type:
        :   [`mathutils.Color`](mathutils.html#mathutils.Color "mathutils.Color") of 3 items in [0, 1], default (0.145098, 0.419608, 0.137255)

    color_attributes
    :   Geometry color attributes

        Type:
        :   [`AttributeGroupGreasePencil`](bpy.types.AttributeGroupGreasePencil.html#bpy.types.AttributeGroupGreasePencil "bpy.types.AttributeGroupGreasePencil") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`Attribute`](bpy.types.Attribute.html#bpy.types.Attribute "bpy.types.Attribute"), (readonly)

    ghost_after_range
    :   Maximum number of frames to show after current frame (0 = don’t show any frames after current)

        Type:
        :   int in [0, 120], default 1

    ghost_before_range
    :   Maximum number of frames to show before current frame (0 = don’t show any frames before current)

        Type:
        :   int in [0, 120], default 1

    layer_groups
    :   Grease Pencil layer groups

        Type:
        :   [`GreasePencilv3LayerGroup`](bpy.types.GreasePencilv3LayerGroup.html#bpy.types.GreasePencilv3LayerGroup "bpy.types.GreasePencilv3LayerGroup") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`GreasePencilLayerGroup`](bpy.types.GreasePencilLayerGroup.html#bpy.types.GreasePencilLayerGroup "bpy.types.GreasePencilLayerGroup"), (readonly)

    layers
    :   Grease Pencil layers

        Type:
        :   [`GreasePencilv3Layers`](bpy.types.GreasePencilv3Layers.html#bpy.types.GreasePencilv3Layers "bpy.types.GreasePencilv3Layers") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`GreasePencilLayer`](bpy.types.GreasePencilLayer.html#bpy.types.GreasePencilLayer "bpy.types.GreasePencilLayer"), (readonly)

    materials
    :   Type:
        :   [`IDMaterials`](bpy.types.IDMaterials.html#bpy.types.IDMaterials "bpy.types.IDMaterials") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`Material`](bpy.types.Material.html#bpy.types.Material "bpy.types.Material"), (readonly)

    onion_factor
    :   Change fade opacity of displayed onion frames

        Type:
        :   float in [0, 1], default 0.5

    onion_keyframe_type
    :   Type of keyframe (for filtering)

        - `ALL`
          All – Include all Keyframe types.
        - `KEYFRAME`
          Keyframe – Normal keyframe, e.g. for key poses.
        - `BREAKDOWN`
          Breakdown – A breakdown pose, e.g. for transitions between key poses.
        - `MOVING_HOLD`
          Moving Hold – A keyframe that is part of a moving hold.
        - `EXTREME`
          Extreme – An ‘extreme’ pose, or some other purpose as needed.
        - `JITTER`
          Jitter – A filler or baked keyframe for keying on ones, or some other purpose as needed.
        - `GENERATED`
          Generated – A key generated automatically by a tool, not manually created.

        Type:
        :   enum in [`'ALL'`, `'KEYFRAME'`, `'BREAKDOWN'`, `'MOVING_HOLD'`, `'EXTREME'`, `'JITTER'`, `'GENERATED'`], default `'ALL'`

    onion_mode
    :   Mode to display frames

        - `ABSOLUTE`
          Frames – Frames in absolute range of the scene frame.
        - `RELATIVE`
          Keyframes – Frames in relative range of the Grease Pencil keyframes.
        - `SELECTED`
          Selected – Only selected keyframes.

        Type:
        :   enum in [`'ABSOLUTE'`, `'RELATIVE'`, `'SELECTED'`], default `'ABSOLUTE'`

    stroke_depth_order
    :   Defines how the strokes are ordered in 3D space (for objects not displayed ‘In Front’)

        Type:
        :   enum in [Stroke Depth Order Items](bpy_types_enum_items/stroke_depth_order_items.html#rna-enum-stroke-depth-order-items), default `'2D'`

    use_autolock_layers
    :   Automatically lock all layers except the active one to avoid accidental changes

        Type:
        :   boolean, default False

    use_ghost_custom_colors
    :   Use custom colors for ghost frames

        Type:
        :   boolean, default False

    use_onion_fade
    :   Display onion keyframes with a fade in color transparency

        Type:
        :   boolean, default False

    use_onion_loop
    :   Display onion keyframes for looping animations

        Type:
        :   boolean, default False

    *classmethod* bl_rna_get_subclass(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The RNA type or default when not found.

        Return type:
        :   [`bpy.types.Struct`](bpy.types.Struct.html#bpy.types.Struct "bpy.types.Struct") subclass

    *classmethod* bl_rna_get_subclass_py(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The class or default when not found.

        Return type:
        :   type