handanim.core package

Submodules

handanim.core.animation module

class handanim.core.animation.AnimationEvent(type: AnimationEventType, start_time: float = 0, duration: float = 0, easing_fun=None, data: dict = None)

Bases: object

Represents an animation event occurring on a scene with configurable properties.

Parameters:

  • type (AnimationEventType) – The type of animation to be performed.

  • start_time (float, optional) – The starting time point of the animation in seconds. Defaults to 0.

  • duration (float, optional) – The duration of the animation in seconds. Defaults to 0.

  • easing_fun (callable, optional) – An optional easing function to modify animation progression. Defaults to None.

  • data (dict, optional) – Additional configuration data specific to the animation type. Defaults to an empty dict.

apply(opsset: OpsSet, progress: float) → OpsSet

Applies the progress percentage of the given animation event to the given opsset

subdivide(n_division: int)

Returns subdivision of an event into n_division segments

class handanim.core.animation.AnimationEventType(value)

Bases: Enum

An enumeration representing different types of animation events.

COMPOSITE = 'composite'
CREATION = 'creation'
DELETION = 'deletion'
MUTATION = 'mutation'
class handanim.core.animation.CompositeAnimationEvent(events: List[AnimationEvent], easing_fun=None, data=None)

Bases: AnimationEvent

Represents a composite animation event that combines multiple animation events.

Parameters:

  • events (List[AnimationEvent]) – A list of animation events to be combined.

  • easing_fun (callable, optional) – An optional easing function to apply to the composite event.

  • data (dict, optional) – Additional configuration data for the composite animation event.

events

The list of animation events in the composite event.

Type:

List[AnimationEvent]

handanim.core.draw_ops module

class handanim.core.draw_ops.Ops(type: OpsType, data: Any, partial: float = 1.0)

Bases: object

Represents a drawing operation to be performed in the animation system.

SETUP_OPS_TYPES

Types of operations considered setup operations.

Type:

List[OpsType]

type

The type of drawing operation.

Type:

OpsType

data

The data used to perform the drawing operation.

Type:

Any

partial

Fraction of the operation to be performed, defaults to 1.0.

Type:

float, optional

SETUP_OPS_TYPES = [OpsType.SET_PEN, OpsType.MOVE_TO, OpsType.METADATA]
class handanim.core.draw_ops.OpsSet(initial_set: List[dict | Ops] = [])

Bases: object

Represents a collection of drawing operations with methods for manipulation and rendering.

Provides functionality to: - Add, extend, and manage a list of drawing operations - Calculate bounding box and center of gravity - Perform transformations like translation, scaling, and rotation - Render operations to a Cairo context

opsset

A list of drawing operations to be performed.

Type:

List[Ops]

add(ops: Ops | dict)
extend(other_opsset: Any)
get_bbox() → Tuple[float, float, float, float]

Calculate the bounding box that encompasses all points in the operations set.

Returns:

A tuple of (min_x, min_y, max_x, max_y) representing the coordinates of the bounding box. Returns (0, 0, 0, 0) if the operations set is empty.

Note

Currently supports only list-type point data. Curve calculations are not fully implemented.

get_center_of_gravity() → Tuple[float, float]

Calculate the approximate geometric center of the operations set.

Returns:

A tuple of (x, y) coordinates representing the center point, computed as the midpoint of the bounding box.

get_current_point()

Retrieves the current drawing point from the last operation in the operations set.

Returns:

A tuple (x, y) representing the current drawing point, considering partial operations and different types of drawing operations (move, line, curve, quadratic curve). Returns (0, 0) if no valid point can be determined.

get_last_ops(start_index: int = 0) → Tuple[float | None, Ops | None]

Retrieve the last valid operation from the operations set.

Parameters:

start_index (int, optional) – Starting index for searching backwards. Defaults to 0.

Returns:

A tuple containing the index and the last valid operation. Returns (None, None) if no valid operation is found.

Return type:

Tuple[Optional[float], Optional[Ops]]

Note

Valid operations include MOVE_TO, LINE_TO, CURVE_TO, and QUAD_CURVE_TO.

render(ctx: Context, initial_mode: str = 'stroke')

Renders the operation set on a Cairo graphics context.

This method iterates through a series of drawing operations and applies them to the provided Cairo context. It supports various operation types including move, line, curve, and quadratic curve drawing, as well as path closing and pen/style configuration.

Parameters:

  • ctx (cairo.Context) – The Cairo graphics context to render operations on.

  • initial_mode (str, optional) – The initial rendering mode, either “stroke” or “fill”. Defaults to “stroke”.

Raises:

NotImplementedError – If an unsupported operation type is encountered.

rotate(angle: float)

Rotates the operations in the opsset by a specified angle around its center of gravity.

Applies a rotation transformation to all point-based operations relative to the current center of gravity. The rotation is performed in degrees and uses a standard 2D rotation matrix.

Parameters:

angle (float) – The rotation angle in degrees. Positive values rotate counterclockwise.

scale(scale_x: float, scale_y: float | None = None)

Scales the operations in the opsset relative to its center of gravity.

Applies uniform or non-uniform scaling to all point-based operations. If only scale_x is provided, the scaling is uniform in both x and y directions. The scaling is performed relative to the current center of gravity of the operations.

Parameters:

  • scale_x (float) – The scaling factor for the x-axis.

  • scale_y (float, optional) – The scaling factor for the y-axis. Defaults to the same value as scale_x for uniform scaling.

translate(offset_x: float, offset_y: float)

Translates all operations in the opsset by a specified (x, y) offset.

Applies the translation relative to the current center of gravity of the operations. Modifies the operations in-place by adding the offset to each point’s coordinates. Non-point operations (like set pen type) are preserved without modification.

Parameters:

  • offset_x (float) – The x-axis translation amount

  • offset_y (float) – The y-axis translation amount

class handanim.core.draw_ops.OpsType(value)

Bases: Enum

CLOSE_PATH = 'close_path'
CURVE_TO = 'curve_to'
DOT = 'dot'
LINE_TO = 'line_to'
METADATA = 'metadata'
MOVE_TO = 'move_to'
QUAD_CURVE_TO = 'quad_curve_to'
SET_PEN = 'set_pen'

handanim.core.drawable module

class handanim.core.drawable.Drawable(stroke_style: ~handanim.core.styles.StrokeStyle = <handanim.core.styles.StrokeStyle object>, sketch_style: ~handanim.core.styles.SketchStyle = <handanim.core.styles.SketchStyle object>, fill_style: ~handanim.core.styles.FillStyle | None = None, glow_dot_hint: ~typing.Dict | bool | None = None)

Bases: object

A base class representing a drawable object with drawing, transformation, and styling capabilities.

This class provides a standard interface for creating drawable objects that can be drawn on a canvas. Subclasses must implement the draw() method to define specific drawing operations.

id

A unique hexadecimal identifier for the drawable object.

Type:

str

stroke_style

Defines the stroke styling for the drawable.

Type:

StrokeStyle

sketch_style

Defines the sketch styling for the drawable.

Type:

SketchStyle

fill_style

Optional fill style for the drawable.

Type:

Optional[FillStyle]

glow_dot_hint

Optional configuration for glow dot rendering.

Type:

Dict

draw()

Abstract method to generate drawing operations.

translate()

Creates a translated version of the drawable.

scale()

Creates a scaled version of the drawable.

rotate()

Creates a rotated version of the drawable.

draw() → OpsSet

Provides the list of operations to be performed to draw this particular drawable object on the canvas

rotate(angle: float)

Rotates the drawable object by the given angle

scale(scale_x: float, scale_y: float)

Scales the drawable object by the given scale factors

translate(offset_x: float, offset_y: float)

Translates the drawable object by the given offset

class handanim.core.drawable.DrawableCache

Bases: object

A cache management class for storing and retrieving drawable objects and their corresponding operation sets.

Provides methods to: - Store and retrieve drawable objects and their computed operation sets - Check for existing drawable operation sets - Calculate bounding boxes for multiple drawables

cache

A mapping of drawable IDs to their computed operation sets

Type:

dict[str, OpsSet]

drawables

A mapping of drawable IDs to their drawable objects

Type:

dict[str, Drawable]

calculate_bounding_box(drawables: List[Drawable])

Calculates the bounding box for a list of drawables stored in the cache

get_drawable(drawable_id: str) → Drawable
get_drawable_opsset(drawable_id: str) → OpsSet
has_drawable_oppset(drawable_id: str) → bool
set_drawable_opsset(drawable: Drawable)
class handanim.core.drawable.DrawableFill(bound_box_list: ~typing.List[~typing.List[~typing.Tuple[float, float]]], fill_style: ~handanim.core.styles.FillStyle = <handanim.core.styles.FillStyle object>, sketch_style: ~handanim.core.styles.SketchStyle = <handanim.core.styles.SketchStyle object>)

Bases: object

A class representing a fill style for drawable objects, defining how an area should be filled.

Allows specification of bounding boxes, fill styles, and sketch styles for rendering.

bound_box_list

Defines the bounding boxes for filling

Type:

List[List[Tuple[float, float]]]

fill_style

Specifies the fill style parameters

Type:

FillStyle

sketch_style

Specifies the sketch style parameters

Type:

SketchStyle

Raises:

NotImplementedError – If the fill method is not implemented in a subclass

fill() → OpsSet
class handanim.core.drawable.DrawableGroup(elements: List[Drawable], grouping_method='parallel', *args, **kwargs)

Bases: Drawable

A drawable group that manages a collection of drawable elements with specified grouping behavior.

Allows applying transformations or animations to multiple drawable objects either in parallel or series.

Parameters:

  • elements (List[Drawable]) – A list of drawable objects to be grouped.

  • grouping_method (str, optional) – Determines how animations are applied. Can be ‘parallel’ (default) or ‘series’. Defaults to ‘parallel’.

elements

The list of drawable elements in the group.

Type:

List[Drawable]

grouping_method

The method used for applying transformations.

Type:

str

draw() → OpsSet

This is useful to apply transformations to the entire group of objects at once

class handanim.core.drawable.TransformedDrawable(base_drawable: Drawable, transformation_function: callable, transformation_args: dict = {}, **kwargs)

Bases: Drawable

A drawable object that applies a transformation to a base drawable.

Allows dynamic transformation of drawable objects by applying a specified transformation function to the base drawable’s operation set.

base_drawable

The original drawable object to be transformed

Type:

Drawable

transformation_function

Name of the transformation method to apply

Type:

callable

transformation_args

Arguments for the transformation method

Type:

dict

Raises:

ValueError – If the transformation function is invalid or not callable

draw() → OpsSet

Overrides the draw method of the base drawable object

handanim.core.scene module

class handanim.core.scene.Scene(width: int = 1280, height: int = 720, fps: int = 24, background_color: tuple[float, float, float] = (1, 1, 1), viewport: Viewport | None = None)

Bases: object

A Scene represents an animation composition where drawables and events are managed.

Handles the creation, timeline, and rendering of animated graphics with configurable viewport, background, and frame settings. Supports creating snapshots and full video renders of animated sequences.

width

Width of the rendering surface in pixels.

Type:

int

height

Height of the rendering surface in pixels.

Type:

int

fps

Frames per second for video rendering.

Type:

int

background_color

RGB color for scene background.

Type:

tuple

viewport

Defines coordinate mapping between world and screen space.

Type:

Viewport

add(event: AnimationEvent, drawable: Drawable)

Adds an animation event to a drawable primitive in the scene.

Handles different scenarios including: - Composite animation events (recursively adding sub-events) - Drawable groups with parallel or sequential event distribution - Single event and drawable cases

Manages event tracking, drawable caching, and object timelines.

Parameters:

  • event (AnimationEvent) – The animation event to be added.

  • drawable (Drawable) – The drawable primitive to apply the event to.

create_event_timeline(fps: int = 30, max_length: float | None = None, verbose: bool = False)

Creates a timeline of animation events and calculates the OpsSet for each frame.

This method processes all drawable events, determines active objects at each frame, and generates a list of OpsSet operations representing the animation progression.

Parameters:

  • fps (int, optional) – Frames per second for the animation. Defaults to 30.

  • max_length (Optional[float], optional) – Maximum duration of the animation. Defaults to None.

  • verbose (bool, optional) – If True, provides detailed logging during animation calculation. Defaults to False.

Returns:

A list of OpsSet operations for each frame in the animation.

Return type:

List[OpsSet]

get_active_objects(t: float)

Determines the list of object IDs that are active at a specific time point.

Calculates object visibility by toggling their active status based on their timeline. An object becomes active when its timeline reaches a time point, and its status alternates with each subsequent time point.

Parameters:

t (float) – The time point (in seconds) to check object activity.

Returns:

A list of object IDs that are active at the given time point.

Return type:

List[str]

get_animated_opsset(opsset: OpsSet, animation_events: List[Tuple[AnimationEvent, float]], verbose: bool = False)

Applies a sequence of animation events to an OpsSet and returns the transformed result.

This method progressively modifies an initial OpsSet by applying a list of animation events at specified progression points. Each event transforms the OpsSet based on its current progress.

Parameters:

  • opsset (OpsSet) – The initial set of operations to be animated.

  • animation_events (List[Tuple[AnimationEvent, float]]) – A list of animation events with their corresponding progress values.

  • verbose (bool, optional) – If True, prints detailed information about each event application. Defaults to False.

Returns:

The final OpsSet after applying all specified animation events.

Return type:

OpsSet

get_viewport_bounds() → Tuple[float, float, float, float]

Retrieves the viewport’s boundaries in world coordinates.

Returns:

A tuple containing (x_min, x_max, y_min, y_max) representing the viewport’s world coordinate boundaries.

Return type:

Tuple[float, float, float, float]

render(output_path: str, max_length: float | None = None, verbose=False)

Render the animation as a video file.

This method generates a video by creating a timeline of animation events and rendering each frame using Cairo graphics. The video is saved to the specified output path with the configured frame rate.

Parameters:

  • output_path (str) – Path to save the output video file.

  • max_length (Optional[float], optional) – Maximum duration of the animation. Defaults to None.

  • verbose (bool, optional) – Enable verbose logging for rendering process. Defaults to False.

render_snapshot(output_path: str, frame_in_seconds: float, max_length: float | None = None, verbose: bool = False)

Render a snapshot of the animation at a specific time point as an SVG file.

This method is useful for debugging and inspecting the state of an animation at a precise moment. It generates a single frame from the animation timeline and saves it as an SVG image.

Parameters:

  • output_path (str) – Path to the output SVG file.

  • frame_in_seconds (float) – The exact time point (in seconds) to render.

  • max_length (Optional[float], optional) – Total duration of the animation. Defaults to None.

  • verbose (bool, optional) – Enable verbose logging. Defaults to False.

handanim.core.styles module

class handanim.core.styles.FillStyle(**kwargs)

Bases: object

A class that defines the styling configurations for the fills of the primitives.

Allows customization of fill appearance including color, opacity, fill pattern, hachure settings, and fill weight. Defaults to a black fill with full opacity and hachure pattern.

options

Raw keyword arguments passed during initialization

Type:

dict

color

RGB color tuple, defaults to black (0, 0, 0)

Type:

tuple

opacity

Fill opacity from 0-1, defaults to 1

Type:

float

fill_pattern

Pattern for filling, defaults to “hachure”

Type:

str

hachure_angle

Angle of hachure lines in degrees, defaults to 45

Type:

int

hachure_gap

Gap between hachure lines, defaults to 4

Type:

int

hachure_line_width

Width of hachure lines, defaults to 1

Type:

int

zigzag_offset

Offset for zigzag pattern, defaults to -1

Type:

int

fill_weight

Weight/thickness of fill, defaults to 2

Type:

int

class handanim.core.styles.SketchStyle(**kwargs)

Bases: object

A class that defines the styling configurations for sketchy, hand-drawn style renderings.

bowing

Amount of bowing/waviness in lines, defaults to 1

Type:

int

max_random_offset

Maximum random offset for sketch lines, defaults to 2

Type:

int

roughness

Roughness of sketch lines, defaults to 1

Type:

int

curve_tightness

Tightness of curves, defaults to 0

Type:

int

curve_fitting

Curve fitting parameter, defaults to 0.95

Type:

float

curve_step_count

Number of steps for curve rendering, defaults to 9

Type:

int

disable_multi_stroke

Flag to disable multi-stroke rendering, defaults to False

Type:

bool

disable_font_mixture

Flag to disable font mixture, defaults to True

Type:

bool

class handanim.core.styles.StrokePressure(value)

Bases: Enum

A class that defines the pressure of the strokes

CONSTANT = 'constant'
INVERSE = 'inverse'
PROPORTIONAL = 'proportional'
class handanim.core.styles.StrokeStyle(**kwargs)

Bases: object

A class that defines the styling configurations for the strokes of the boundaries of the primitives.

Allows customization of stroke appearance including color, width, opacity, and pressure characteristics. Defaults to a black, 1-pixel wide constant pressure stroke with full opacity.

options

Raw keyword arguments passed during initialization

Type:

dict

color

RGB color tuple, defaults to black (0, 0, 0)

Type:

tuple

width

Stroke width in pixels, defaults to 1

Type:

int/float

opacity

Stroke opacity from 0-1, defaults to 1

Type:

float

stroke_pressure

Pressure mode for stroke rendering, defaults to StrokePressure.CONSTANT

Type:

StrokePressure

handanim.core.utils module

handanim.core.utils.cairo_surface_to_numpy(surface: ImageSurface)

Convert a Cairo surface to a numpy array with RGBA color channel ordering.

Transforms the image surface data from Cairo’s ARGB format to a numpy array with RGBA color channels, suitable for further image processing or saving.

Parameters:

surface (cairo.ImageSurface) – The source Cairo image surface to convert

Returns:

A numpy array representing the image with shape (height, width, 4)

and dtype np.uint8, with color channels reordered from BGR to RGB

Return type:

numpy.ndarray

handanim.core.utils.get_bezier_points_from_quadcurve(p0: Tuple[float, float], q1: Tuple[float, float], q2: Tuple[float, float])

Convert a quadratic Bezier curve to a cubic Bezier curve representation.

Transforms control points from a quadratic curve (with two control points) to an equivalent cubic curve (with three control points) using linear interpolation.

Parameters:

  • p0 (Tuple[float, float]) – Starting point of the quadratic curve

  • q1 (Tuple[float, float]) – Control point of the quadratic curve

  • q2 (Tuple[float, float]) – Ending point of the quadratic curve

Returns:

Intermediate control points for the cubic Bezier curve

Return type:

Tuple[list, list, list]

handanim.core.utils.slice_bezier(p0, p1, p2, p3, t)

Slice a Bezier curve at a given parameter t.

Computes intermediate points along a cubic Bezier curve at a specified interpolation point.

Parameters:

  • p0 (array-like) – Starting point of the Bezier curve

  • p1 (array-like) – First control point

  • p2 (array-like) – Second control point

  • p3 (array-like) – Ending point of the Bezier curve

  • t (float) – Interpolation parameter between 0 and 1

Returns:

A list of three points representing the sliced Bezier curve segment

Return type:

list

handanim.core.viewport module

class handanim.core.viewport.Viewport(world_xrange: Tuple[float, float], world_yrange: Tuple[float, float], screen_width: int = 1920, screen_height: int = 1080, margin: int = 50)

Bases: object

A viewport that transforms mathematical coordinates to pixel coordinates for rendering.

Handles scaling and translation between world coordinates and screen pixels, ensuring proper mapping and centering within a specified margin.

world_xrange

The x-coordinate range in world space.

Type:

Tuple[float, float]

world_yrange

The y-coordinate range in world space.

Type:

Tuple[float, float]

screen_width

The width of the rendering surface in pixels.

Type:

int

screen_height

The height of the rendering surface in pixels.

Type:

int

margin

The margin around the rendered content.

Type:

int

apply_to_context(ctx: Context)

Apply viewport scaling and translation to a cairo context.

Transforms world coordinates to screen pixels by: 1. Calculating scaling factors to fit content within screen margins 2. Translating the context to account for margins 3. Scaling the context to preserve aspect ratio and fit content

Parameters:

ctx (cairo.Context) – The cairo drawing context to transform

Module contents

class handanim.core.AnimationEvent(type: AnimationEventType, start_time: float = 0, duration: float = 0, easing_fun=None, data: dict = None)

Bases: object

Represents an animation event occurring on a scene with configurable properties.

Parameters:

  • type (AnimationEventType) – The type of animation to be performed.

  • start_time (float, optional) – The starting time point of the animation in seconds. Defaults to 0.

  • duration (float, optional) – The duration of the animation in seconds. Defaults to 0.

  • easing_fun (callable, optional) – An optional easing function to modify animation progression. Defaults to None.

  • data (dict, optional) – Additional configuration data specific to the animation type. Defaults to an empty dict.

apply(opsset: OpsSet, progress: float) → OpsSet

Applies the progress percentage of the given animation event to the given opsset

subdivide(n_division: int)

Returns subdivision of an event into n_division segments

class handanim.core.AnimationEventType(value)

Bases: Enum

An enumeration representing different types of animation events.

COMPOSITE = 'composite'
CREATION = 'creation'
DELETION = 'deletion'
MUTATION = 'mutation'
class handanim.core.CompositeAnimationEvent(events: List[AnimationEvent], easing_fun=None, data=None)

Bases: AnimationEvent

Represents a composite animation event that combines multiple animation events.

Parameters:

  • events (List[AnimationEvent]) – A list of animation events to be combined.

  • easing_fun (callable, optional) – An optional easing function to apply to the composite event.

  • data (dict, optional) – Additional configuration data for the composite animation event.

events

The list of animation events in the composite event.

Type:

List[AnimationEvent]

class handanim.core.DrawableGroup(elements: List[Drawable], grouping_method='parallel', *args, **kwargs)

Bases: Drawable

A drawable group that manages a collection of drawable elements with specified grouping behavior.

Allows applying transformations or animations to multiple drawable objects either in parallel or series.

Parameters:

  • elements (List[Drawable]) – A list of drawable objects to be grouped.

  • grouping_method (str, optional) – Determines how animations are applied. Can be ‘parallel’ (default) or ‘series’. Defaults to ‘parallel’.

elements

The list of drawable elements in the group.

Type:

List[Drawable]

grouping_method

The method used for applying transformations.

Type:

str

draw() → OpsSet

This is useful to apply transformations to the entire group of objects at once

class handanim.core.FillStyle(**kwargs)

Bases: object

A class that defines the styling configurations for the fills of the primitives.

Allows customization of fill appearance including color, opacity, fill pattern, hachure settings, and fill weight. Defaults to a black fill with full opacity and hachure pattern.

options

Raw keyword arguments passed during initialization

Type:

dict

color

RGB color tuple, defaults to black (0, 0, 0)

Type:

tuple

opacity

Fill opacity from 0-1, defaults to 1

Type:

float

fill_pattern

Pattern for filling, defaults to “hachure”

Type:

str

hachure_angle

Angle of hachure lines in degrees, defaults to 45

Type:

int

hachure_gap

Gap between hachure lines, defaults to 4

Type:

int

hachure_line_width

Width of hachure lines, defaults to 1

Type:

int

zigzag_offset

Offset for zigzag pattern, defaults to -1

Type:

int

fill_weight

Weight/thickness of fill, defaults to 2

Type:

int

class handanim.core.Scene(width: int = 1280, height: int = 720, fps: int = 24, background_color: tuple[float, float, float] = (1, 1, 1), viewport: Viewport | None = None)

Bases: object

A Scene represents an animation composition where drawables and events are managed.

Handles the creation, timeline, and rendering of animated graphics with configurable viewport, background, and frame settings. Supports creating snapshots and full video renders of animated sequences.

width

Width of the rendering surface in pixels.

Type:

int

height

Height of the rendering surface in pixels.

Type:

int

fps

Frames per second for video rendering.

Type:

int

background_color

RGB color for scene background.

Type:

tuple

viewport

Defines coordinate mapping between world and screen space.

Type:

Viewport

add(event: AnimationEvent, drawable: Drawable)

Adds an animation event to a drawable primitive in the scene.

Handles different scenarios including: - Composite animation events (recursively adding sub-events) - Drawable groups with parallel or sequential event distribution - Single event and drawable cases

Manages event tracking, drawable caching, and object timelines.

Parameters:

  • event (AnimationEvent) – The animation event to be added.

  • drawable (Drawable) – The drawable primitive to apply the event to.

create_event_timeline(fps: int = 30, max_length: float | None = None, verbose: bool = False)

Creates a timeline of animation events and calculates the OpsSet for each frame.

This method processes all drawable events, determines active objects at each frame, and generates a list of OpsSet operations representing the animation progression.

Parameters:

  • fps (int, optional) – Frames per second for the animation. Defaults to 30.

  • max_length (Optional[float], optional) – Maximum duration of the animation. Defaults to None.

  • verbose (bool, optional) – If True, provides detailed logging during animation calculation. Defaults to False.

Returns:

A list of OpsSet operations for each frame in the animation.

Return type:

List[OpsSet]

get_active_objects(t: float)

Determines the list of object IDs that are active at a specific time point.

Calculates object visibility by toggling their active status based on their timeline. An object becomes active when its timeline reaches a time point, and its status alternates with each subsequent time point.

Parameters:

t (float) – The time point (in seconds) to check object activity.

Returns:

A list of object IDs that are active at the given time point.

Return type:

List[str]

get_animated_opsset(opsset: OpsSet, animation_events: List[Tuple[AnimationEvent, float]], verbose: bool = False)

Applies a sequence of animation events to an OpsSet and returns the transformed result.

This method progressively modifies an initial OpsSet by applying a list of animation events at specified progression points. Each event transforms the OpsSet based on its current progress.

Parameters:

  • opsset (OpsSet) – The initial set of operations to be animated.

  • animation_events (List[Tuple[AnimationEvent, float]]) – A list of animation events with their corresponding progress values.

  • verbose (bool, optional) – If True, prints detailed information about each event application. Defaults to False.

Returns:

The final OpsSet after applying all specified animation events.

Return type:

OpsSet

get_viewport_bounds() → Tuple[float, float, float, float]

Retrieves the viewport’s boundaries in world coordinates.

Returns:

A tuple containing (x_min, x_max, y_min, y_max) representing the viewport’s world coordinate boundaries.

Return type:

Tuple[float, float, float, float]

render(output_path: str, max_length: float | None = None, verbose=False)

Render the animation as a video file.

This method generates a video by creating a timeline of animation events and rendering each frame using Cairo graphics. The video is saved to the specified output path with the configured frame rate.

Parameters:

  • output_path (str) – Path to save the output video file.

  • max_length (Optional[float], optional) – Maximum duration of the animation. Defaults to None.

  • verbose (bool, optional) – Enable verbose logging for rendering process. Defaults to False.

render_snapshot(output_path: str, frame_in_seconds: float, max_length: float | None = None, verbose: bool = False)

Render a snapshot of the animation at a specific time point as an SVG file.

This method is useful for debugging and inspecting the state of an animation at a precise moment. It generates a single frame from the animation timeline and saves it as an SVG image.

Parameters:

  • output_path (str) – Path to the output SVG file.

  • frame_in_seconds (float) – The exact time point (in seconds) to render.

  • max_length (Optional[float], optional) – Total duration of the animation. Defaults to None.

  • verbose (bool, optional) – Enable verbose logging. Defaults to False.

class handanim.core.SketchStyle(**kwargs)

Bases: object

A class that defines the styling configurations for sketchy, hand-drawn style renderings.

bowing

Amount of bowing/waviness in lines, defaults to 1

Type:

int

max_random_offset

Maximum random offset for sketch lines, defaults to 2

Type:

int

roughness

Roughness of sketch lines, defaults to 1

Type:

int

curve_tightness

Tightness of curves, defaults to 0

Type:

int

curve_fitting

Curve fitting parameter, defaults to 0.95

Type:

float

curve_step_count

Number of steps for curve rendering, defaults to 9

Type:

int

disable_multi_stroke

Flag to disable multi-stroke rendering, defaults to False

Type:

bool

disable_font_mixture

Flag to disable font mixture, defaults to True

Type:

bool

class handanim.core.StrokeStyle(**kwargs)

Bases: object

A class that defines the styling configurations for the strokes of the boundaries of the primitives.

Allows customization of stroke appearance including color, width, opacity, and pressure characteristics. Defaults to a black, 1-pixel wide constant pressure stroke with full opacity.

options

Raw keyword arguments passed during initialization

Type:

dict

color

RGB color tuple, defaults to black (0, 0, 0)

Type:

tuple

width

Stroke width in pixels, defaults to 1

Type:

int/float

opacity

Stroke opacity from 0-1, defaults to 1

Type:

float

stroke_pressure

Pressure mode for stroke rendering, defaults to StrokePressure.CONSTANT

Type:

StrokePressure