Blender Grease Pencil

Overview

Create 2D drawings and animations in Blender's 3D space using Grease Pencil and Python. Build strokes from point data, manage layers and frames, apply Grease Pencil modifiers, and animate 2D content, all scriptable from the terminal.

This skill targets the Grease Pencil v3 API (Blender 5.x, checked against the 5.2 Python API reference). The old v2 API (gpencil_add, layer.info, stroke.points.add(), grease_pencil_modifiers, GP_THICK) no longer exists; scripts written for Blender 2.8-4.2 must be ported. In Blender 4.3-4.5 the v3 data-blocks lived in bpy.data.grease_pencils_v3; from 5.0 bpy.data.grease_pencils is v3.

Data model: a GreasePencil data-block has layers (and layer groups); a layer has frames keyed by frame number; each frame points to a drawing; a drawing holds strokes stored as curve and point attributes (position, radius, opacity, material_index, cyclic).

Instructions

1. Create a Grease Pencil object

import bpy

gp_data = bpy.data.grease_pencils.new("MyDrawing")
gp_obj = bpy.data.objects.new("MyDrawing", gp_data)   # obj.type == 'GREASEPENCIL'
bpy.context.collection.objects.link(gp_obj)

# Or use the operator
bpy.ops.object.grease_pencil_add(type='EMPTY')   # EMPTY, STROKE, MONKEY, LINEART_SCENE, LINEART_OBJECT, LINEART_COLLECTION
gp_obj = bpy.context.active_object

Prefer the data-level route in scripts: it works in --background mode and gives you an object with no pre-made layers or frames to trip over.

2. Add layers and frames

gp_data = gp_obj.data

layer = gp_data.layers.new("Outlines", set_active=True)   # the name is layer.name
layer.blend_mode = 'REGULAR'   # REGULAR, HARDLIGHT, ADD, SUBTRACT, MULTIPLY, DIVIDE
layer.opacity = 1.0
layer.use_lights = False

frame = layer.frames.new(1)    # raises if frame 1 already exists on this layer
drawing = frame.drawing        # the container for strokes

# Copy, move, or remove keyframes
layer.frames.copy(1, 12)
layer.frames.move(12, 13)
layer.frames.remove(13)

Layers can be grouped: gp_data.layer_groups and gp_data.layers.new(name, layer_group=group).

3. Draw strokes programmatically

Strokes are added with drawing.add_strokes(sizes) (one point count per stroke) and then filled through attributes. The Blender docs recommend the attributes API over drawing.strokes[n] for anything beyond small scripts, and warn that stroke slices become invalid after the point or curve count changes.

def add_stroke(drawing, points, radius=0.02, material_index=0, cyclic=False):
    attrs = drawing.attributes
    first_curve = attrs.domain_size('CURVE')
    first_point = attrs.domain_size('POINT')
    drawing.add_strokes([len(points)])

    pos = attrs["position"].data
    rad = attrs["radius"].data
    for i, co in enumerate(points):
        pos[first_point + i].vector = co
        rad[first_point + i].value = radius      # radius, not width: line width is about 2 * radius

    for name, kind, value in (("material_index", 'INT', material_index),
                              ("cyclic", 'BOOLEAN', cyclic)):
        attr = attrs.get(name) or attrs.new(name, kind, 'CURVE')   # created on demand
        attr.data[first_curve].value = value
    drawing.tag_positions_changed()

add_stroke(drawing, [(0, 0, 0), (1, 0.5, 0), (2, 1, 0), (3, 0.5, 0), (4, 0, 0)])

Radius is in scene units (default 0.01 is thin); use 0.02-0.05 for visible lines at normal camera distances. Points also carry opacity (0-1).

4. Create Grease Pencil materials

mat_solid = bpy.data.materials.new("GP_Solid")
bpy.data.materials.create_gpencil_data(mat_solid)
style = mat_solid.grease_pencil
style.color = (0.1, 0.1, 0.1, 1.0)          # stroke color
style.fill_color = (0.8, 0.2, 0.2, 1.0)     # fill color
style.show_stroke = True
style.show_fill = True
gp_obj.data.materials.append(mat_solid)     # slot index = stroke material_index

5. Apply Grease Pencil modifiers

Grease Pencil modifiers are ordinary object modifiers in v3: use obj.modifiers with GREASE_PENCIL_* types.

thick = gp_obj.modifiers.new("Thickness", 'GREASE_PENCIL_THICKNESS')
thick.thickness_factor = 1.5                 # use_uniform_thickness + thickness for a fixed value

smooth = gp_obj.modifiers.new("Smooth", 'GREASE_PENCIL_SMOOTH')
smooth.factor = 0.5
smooth.step = 3

tint = gp_obj.modifiers.new("Tint", 'GREASE_PENCIL_TINT')
tint.color = (0.2, 0.5, 1.0)
tint.factor = 0.3

noise = gp_obj.modifiers.new("Noise", 'GREASE_PENCIL_NOISE')   # hand-drawn wobble
noise.factor = 0.5

subdiv = gp_obj.modifiers.new("Subdivide", 'GREASE_PENCIL_SUBDIV')
subdiv.level = 2

build = gp_obj.modifiers.new("Build", 'GREASE_PENCIL_BUILD')   # animated reveal
build.mode = 'SEQUENTIAL'      # SEQUENTIAL, CONCURRENT, ADDITIVE
build.time_mode = 'FRAMES'     # FRAMES, DRAWSPEED, PERCENTAGE
build.length = 50              # frames the build runs
build.use_restrict_frame_range = True   # then frame_start / frame_end apply
build.frame_start = 1

array = gp_obj.modifiers.new("Array", 'GREASE_PENCIL_ARRAY')
array.count = 5
array.constant_offset = (1.0, 0.0, 0.0)   # also set use_constant_offset = True

Other types follow the same pattern: GREASE_PENCIL_OPACITY, GREASE_PENCIL_COLOR, GREASE_PENCIL_MIRROR, GREASE_PENCIL_OFFSET, GREASE_PENCIL_LINEART, and so on. Every modifier has layer, material and pass filters (tree_node_filter takes a layer name, material_filter a material).

6. Animate frame by frame

import math

layer = gp_obj.data.layers.new("Pulse")
total_frames = 24
for f in range(total_frames):
    drawing = layer.frames.new(f + 1).drawing
    radius = 0.5 + (f / total_frames) * 2.0
    ring = [(radius * math.cos(2 * math.pi * i / 32),
             radius * math.sin(2 * math.pi * i / 32), 0) for i in range(32)]
    add_stroke(drawing, ring, radius=0.03, cyclic=True)

scene = bpy.context.scene
scene.frame_start, scene.frame_end = 1, total_frames

Each frame owns an independent drawing. Frames hold until the next keyframe, so you only create frames where the drawing changes.

7. Drawing guides

Guides (circular, radial, parallel, grid, isometric) are interactive Draw-mode tools in the viewport and have no scripting entry point for generating strokes. In a script, compute constrained points yourself:

def snap_to_grid(point, spacing=1.0):
    return tuple(round(c / spacing) * spacing for c in point)

def snap_to_radial(point, center=(0, 0, 0), num_rays=8):
    dx, dy = point[0] - center[0], point[1] - center[1]
    step = 2 * math.pi / num_rays
    angle = round(math.atan2(dy, dx) / step) * step
    dist = math.hypot(dx, dy)
    return (center[0] + dist * math.cos(angle), center[1] + dist * math.sin(angle), point[2])

Examples

Example 1: Procedural comic panel with a speech bubble

User request: "Create a simple comic panel layout with borders and a speech bubble, saved as a .blend"

import bpy, math

# add_stroke() from step 3 must be defined above this point
gp_data = bpy.data.grease_pencils.new("ComicPanel")
gp_obj = bpy.data.objects.new("ComicPanel", gp_data)
bpy.context.collection.objects.link(gp_obj)

mat_ink = bpy.data.materials.new("GP_Ink")
bpy.data.materials.create_gpencil_data(mat_ink)
mat_ink.grease_pencil.color = (0, 0, 0, 1)
mat_ink.grease_pencil.show_fill = False
gp_data.materials.append(mat_ink)            # index 0

mat_bubble = bpy.data.materials.new("GP_Bubble")
bpy.data.materials.create_gpencil_data(mat_bubble)
mat_bubble.grease_pencil.color = (0, 0, 0, 1)
mat_bubble.grease_pencil.fill_color = (1, 1, 1, 1)
mat_bubble.grease_pencil.show_fill = True
gp_data.materials.append(mat_bubble)         # index 1

def rect(x, y, w, h):
    return [(x, y, 0), (x + w, y, 0), (x + w, y + h, 0), (x, y + h, 0)]

borders = gp_data.layers.new("Borders").frames.new(1).drawing
add_stroke(borders, rect(0, 0, 6, 4), radius=0.05, cyclic=True)
add_stroke(borders, rect(0.2, 0.2, 2.7, 3.6), radius=0.03, cyclic=True)
add_stroke(borders, rect(3.1, 0.2, 2.7, 3.6), radius=0.03, cyclic=True)

bubble = gp_data.layers.new("Bubbles").frames.new(1).drawing
ellipse = [(4.5 + 0.8 * math.cos(2 * math.pi * i / 24), 3.0 + 0.4 * math.sin(2 * math.pi * i / 24), 0.01)
           for i in range(24)]
add_stroke(bubble, ellipse, radius=0.025, material_index=1, cyclic=True)

bpy.ops.wm.save_as_mainfile(filepath="/tmp/comic_panel.blend")

Result: /tmp/comic_panel.blend with two layers ("Borders" with three rectangles, "Bubbles" with a white-filled ellipse). Layers draw in stack order (the default stroke_depth_order is '2D'), so the bubble layer sits above the borders.

Example 2: Handwriting reveal with the Build modifier

User request: "Animate the letters HI being written stroke by stroke"

import bpy

# add_stroke() from step 3 must be defined above this point
gp_data = bpy.data.grease_pencils.new("Handwriting")
gp_obj = bpy.data.objects.new("Handwriting", gp_data)
bpy.context.collection.objects.link(gp_obj)

ink = bpy.data.materials.new("GP_Ink")
bpy.data.materials.create_gpencil_data(ink)
ink.grease_pencil.color = (0.05, 0.05, 0.15, 1)
gp_data.materials.append(ink)

drawing = gp_data.layers.new("Letters").frames.new(1).drawing
add_stroke(drawing, [(0, 0, 0), (0, 2, 0)], radius=0.05)                    # H left bar
add_stroke(drawing, [(0, 1, 0), (1, 1, 0)], radius=0.05)                    # H crossbar
add_stroke(drawing, [(1, 2, 0), (1, 0, 0)], radius=0.05)                    # H right bar
add_stroke(drawing, [(2.5, 2, 0), (2.5, 0, 0)], radius=0.05)                # I

build = gp_obj.modifiers.new("Build", 'GREASE_PENCIL_BUILD')
build.mode = 'SEQUENTIAL'
build.time_mode = 'FRAMES'
build.length = 60

scene = bpy.context.scene
scene.frame_start, scene.frame_end = 1, 60
bpy.ops.wm.save_as_mainfile(filepath="/tmp/handwriting.blend")

Result: scrubbing frames 1-60 shows the four strokes appearing one after another.

Guidelines

• Use bpy.data.grease_pencils.new() for data-level creation; bpy.ops.object.grease_pencil_add() is for quick objects and needs a valid context.
• Assign at least one Grease Pencil material before rendering: strokes without a material slot do not show the colors you intended.
• Stroke thickness is radius per point (scene units), not a pixel line_width; there is no pressure or strength any more (use radius and opacity).
• Never keep references to drawing.strokes[n] across add_strokes, remove_strokes or resize_strokes; re-fetch or use attributes.
• Layer names are layer.name; blend modes are REGULAR, HARDLIGHT, ADD, SUBTRACT, MULTIPLY, DIVIDE (OVERLAY is gone).
• layer.frames.new() fails if the frame number is taken; use layer.get_frame_at() or layer.frames.remove() first.
• Never hardcode enum names from memory: read them, for example [i.identifier for i in bpy.types.Modifier.bl_rna.properties["type"].enum_items].
• Build modifier is the cheapest way to animate stroke reveal without per-frame scripting.
• Scripts here were checked against the API reference, not executed in Blender: run them once in blender --background --python script.py and watch the console before relying on them.