handanim 0.1.0__py3-none-any.whl

handanim/__init__.py

@@ -0,0 +1,96 @@
+from .core import (
+    AnimationEvent,
+    AnimationEventType,
+    CompositeAnimationEvent,
+    Drawable,
+    DrawableGroup,
+    FillStyle,
+    Scene,
+    SketchStyle,
+    StrokeStyle,
+)
+from .primitives import (
+    Arrow,
+    Circle,
+    Curve,
+    CurvedArrow,
+    Ellipse,
+    Eraser,
+    Flowchart,
+    FlowchartConnector,
+    FlowchartDiamond,
+    FlowchartNode,
+    Line,
+    LinearPath,
+    Math,
+    NGon,
+    Polygon,
+    Rectangle,
+    RoundedRectangle,
+    RoundedSquare,
+    Square,
+    Table,
+    TableRevealEvent,
+    Text,
+    VectorSVG,
+)
+from .animations import (
+    CameraAnimation,
+    ColorTransitionAnimation,
+    FadeInAnimation,
+    FadeOutAnimation,
+    RotateAnimation,
+    SketchAnimation,
+    TranslateFromAnimation,
+    TranslateToAnimation,
+    ZoomInAnimation,
+    ZoomOutAnimation,
+)
+
+__all__ = [
+    # Core
+    "Scene",
+    "StrokeStyle",
+    "SketchStyle",
+    "FillStyle",
+    "Drawable",
+    "DrawableGroup",
+    "AnimationEvent",
+    "AnimationEventType",
+    "CompositeAnimationEvent",
+    # Primitives
+    "Line",
+    "LinearPath",
+    "Arrow",
+    "CurvedArrow",
+    "Curve",
+    "Rectangle",
+    "RoundedRectangle",
+    "Square",
+    "RoundedSquare",
+    "Polygon",
+    "NGon",
+    "Ellipse",
+    "Circle",
+    "Text",
+    "Math",
+    "Eraser",
+    "VectorSVG",
+    "FlowchartNode",
+    "FlowchartDiamond",
+    "FlowchartConnector",
+    "Flowchart",
+    "Table",
+    "TableRevealEvent",
+    # Animations
+    "SketchAnimation",
+    "FadeInAnimation",
+    "FadeOutAnimation",
+    "ZoomInAnimation",
+    "ZoomOutAnimation",
+    "TranslateFromAnimation",
+    "TranslateToAnimation",
+    "RotateAnimation",
+    "ColorTransitionAnimation",
+    "CameraAnimation",
+]

handanim/animations/__init__.py

@@ -0,0 +1,20 @@
+from .camera import CameraAnimation
+from .color_transition import ColorTransitionAnimation
+from .fade import FadeInAnimation, FadeOutAnimation
+from .rotate import RotateAnimation
+from .sketch import SketchAnimation
+from .translate import TranslateFromAnimation, TranslateToAnimation
+from .zoom import ZoomInAnimation, ZoomOutAnimation
+
+__all__ = [
+    "SketchAnimation",
+    "FadeInAnimation",
+    "FadeOutAnimation",
+    "ZoomInAnimation",
+    "ZoomOutAnimation",
+    "TranslateFromAnimation",
+    "TranslateToAnimation",
+    "RotateAnimation",
+    "ColorTransitionAnimation",
+    "CameraAnimation",
+]

handanim/animations/camera.py

@@ -0,0 +1,79 @@
+
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import OpsSet
+from ..core.viewport import Viewport
+
+
+class CameraAnimation(AnimationEvent):
+    """
+    Animates the Scene viewport (pan and/or zoom) over time.
+
+    Instead of touching any drawable's OpsSet, this animation changes the world
+    ranges that the Viewport maps to the screen — the "camera" moves, not the content.
+
+    Args:
+        start_time: When the animation begins (seconds).
+        duration: Length of the animation (seconds).
+        easing_fun: Optional easing function applied to progress.
+        data: Dict with optional keys:
+            - "from_xrange" (tuple[float, float]): World x range at progress=0.
+              Defaults to wherever the camera currently is.
+            - "from_yrange" (tuple[float, float]): World y range at progress=0.
+              Defaults to wherever the camera currently is.
+            - "to_xrange"   (tuple[float, float]): World x range at progress=1.
+              Defaults to from_xrange (no movement on x).
+            - "to_yrange"   (tuple[float, float]): World y range at progress=1.
+              Defaults to from_yrange (no movement on y).
+
+    Usage::
+
+        scene.add_camera(CameraAnimation(
+            start_time=5, duration=3,
+            data={
+                "to_xrange": (400, 800),
+                "to_yrange": (200, 600),
+            }
+        ))
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(AnimationEventType.MUTATION, start_time, duration, easing_fun, data)
+
+    def _apply(self, opsset: OpsSet, progress: float) -> OpsSet:
+        # CameraAnimation operates on the Viewport, not on OpsSets.
+        # Returning the opsset unchanged makes it safe if mistakenly used with scene.add().
+        return opsset
+
+    def apply_to_viewport(self, current: Viewport, progress: float) -> Viewport:
+        """
+        Return a new Viewport interpolated toward the target world ranges.
+
+        Args:
+            current: The viewport state immediately before this event (used as
+                     the from_* default when not explicitly specified).
+            progress: Animation progress from 0.0 to 1.0.
+
+        Returns:
+            A new Viewport instance with interpolated world ranges.
+        """
+        from_xrange: tuple[float, float] = self.data.get("from_xrange", current.world_xrange)
+        from_yrange: tuple[float, float] = self.data.get("from_yrange", current.world_yrange)
+        to_xrange: tuple[float, float] = self.data.get("to_xrange", from_xrange)
+        to_yrange: tuple[float, float] = self.data.get("to_yrange", from_yrange)
+
+        new_xrange = (
+            (1 - progress) * from_xrange[0] + progress * to_xrange[0],
+            (1 - progress) * from_xrange[1] + progress * to_xrange[1],
+        )
+        new_yrange = (
+            (1 - progress) * from_yrange[0] + progress * to_yrange[0],
+            (1 - progress) * from_yrange[1] + progress * to_yrange[1],
+        )
+
+        return Viewport(
+            world_xrange=new_xrange,
+            world_yrange=new_yrange,
+            screen_width=current.screen_width,
+            screen_height=current.screen_height,
+            margin=current.margin,
+        )

handanim/animations/color_transition.py

@@ -0,0 +1,46 @@
+
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import Ops, OpsSet, OpsType
+
+
+def _lerp_color(
+    a: tuple[float, float, float],
+    b: tuple[float, float, float],
+    t: float,
+) -> tuple[float, float, float]:
+    return tuple((1 - t) * ca + t * cb for ca, cb in zip(a, b, strict=False))  # type: ignore[return-value]
+
+
+class ColorTransitionAnimation(AnimationEvent):
+    """
+    Interpolates every SET_PEN color in an OpsSet from `start_color` to `end_color`.
+
+    At progress=0 all strokes are rendered with `start_color`; at progress=1 they
+    use `end_color`.  The fill color (if present) is interpolated identically.
+
+    Args:
+        start_time: When the animation begins (seconds).
+        duration: Length of the animation (seconds).
+        easing_fun: Optional easing function.
+        data: Dict with keys:
+            - "start_color" (tuple[float,float,float]): RGB at progress 0. Required.
+            - "end_color"   (tuple[float,float,float]): RGB at progress 1. Required.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(AnimationEventType.MUTATION, start_time, duration, easing_fun, data)
+        self.start_color: tuple[float, float, float] = self.data.get("start_color", (0.0, 0.0, 0.0))
+        self.end_color: tuple[float, float, float] = self.data.get("end_color", (1.0, 1.0, 1.0))
+
+    def _apply(self, opsset: OpsSet, progress: float) -> OpsSet:
+        current_color = _lerp_color(self.start_color, self.end_color, progress)
+        new_ops = []
+        for op in opsset.opsset:
+            if op.type == OpsType.SET_PEN:
+                pen_data = dict(op.data).copy()
+                if "color" in pen_data:
+                    pen_data["color"] = current_color
+                new_ops.append(Ops(type=OpsType.SET_PEN, data=pen_data))
+            else:
+                new_ops.append(op)
+        return OpsSet(initial_set=new_ops)

handanim/animations/fade.py

@@ -0,0 +1,60 @@
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import Ops, OpsSet, OpsType
+
+
+class FadeInAnimation(AnimationEvent):
+    """
+    A class representing a fade-in animation event that gradually increases the opacity of elements.
+
+    This animation applies a progressive opacity change from 0 to 1 over a specified duration,
+    creating a smooth fade-in effect for graphical elements.
+
+    Args:
+        start_time (float, optional): The time at which the animation begins. Defaults to 0.
+        duration (float, optional): The total duration of the animation. Defaults to 0.
+        easing_fun (callable, optional): An optional function to modify the animation's progress curve. Defaults to None.
+        data (dict, optional): Additional data associated with the animation. Defaults to None.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(AnimationEventType.CREATION, start_time, duration, easing_fun, data)
+
+    def _opsset_apply(self, opsset: OpsSet, progress: float):
+        current_ops_list = []
+        for op in opsset.opsset:
+            if op.type == OpsType.SET_PEN:
+                modified_data = {k: progress if k == "opacity" else v for k, v in op.data.items()}
+                current_ops_list.append(Ops(type=OpsType.SET_PEN, data=modified_data, partial=op.partial, meta=op.meta))
+            elif op.type == OpsType.IMAGE and isinstance(op.data, dict):
+                modified_data = dict(op.data)
+                modified_data["opacity"] = progress
+                current_ops_list.append(Ops(type=OpsType.IMAGE, data=modified_data, partial=op.partial, meta=op.meta))
+            else:
+                current_ops_list.append(op)
+        new_opsset = OpsSet(initial_set=current_ops_list)
+        return new_opsset
+
+    def _apply(self, opsset: OpsSet, progress: float):
+        return self._opsset_apply(opsset, progress)
+
+
+class FadeOutAnimation(FadeInAnimation):
+    """
+    A class representing a fade-out animation event that gradually decreases the opacity of elements.
+
+    This animation applies a progressive opacity change from 1 to 0 over a specified duration,
+    creating a smooth fade-out effect for graphical elements.
+
+    Args:
+        start_time (float, optional): The time at which the animation begins. Defaults to 0.
+        duration (float, optional): The total duration of the animation. Defaults to 0.
+        easing_fun (callable, optional): An optional function to modify the animation's progress curve. Defaults to None.
+        data (dict, optional): Additional data associated with the animation. Defaults to None.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(start_time, duration, easing_fun, data)
+        self.type = AnimationEventType.DELETION  # override the type
+
+    def _apply(self, opsset, progress):
+        return super()._apply(opsset, 1 - progress)

handanim/animations/rotate.py

@@ -0,0 +1,31 @@
+
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import OpsSet
+
+
+class RotateAnimation(AnimationEvent):
+    """
+    Animates a rotation of an OpsSet from 0 to `angle` degrees over the duration.
+
+    The rotation is applied around the center of gravity by default, or around
+    a fixed `center` point if provided in data.
+
+    Args:
+        start_time: When the animation begins (seconds).
+        duration: Length of the animation (seconds).
+        easing_fun: Optional easing function.
+        data: Dict with optional keys:
+            - "angle" (float): Total rotation angle in degrees. Default 360.
+            - "center" (tuple[float, float]): Fixed pivot point. Default: center of gravity.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(AnimationEventType.MUTATION, start_time, duration, easing_fun, data)
+        self.angle = self.data.get("angle", 360)
+        self.center: tuple[float, float] | None = self.data.get("center", None)
+
+    def _apply(self, opsset: OpsSet, progress: float) -> OpsSet:
+        new_opsset = OpsSet(initial_set=opsset.opsset)
+        pivot = self.center if self.center is not None else new_opsset.get_center_of_gravity()
+        new_opsset.rotate(self.angle * progress, center_of_rotation=pivot)
+        return new_opsset

handanim/animations/sketch.py

@@ -0,0 +1,143 @@
+import numpy as np
+
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import Ops, OpsSet, OpsType
+from ..core.styles import FillStyle
+from ..primitives.ellipse import GlowDot
+
+
+class SketchAnimation(AnimationEvent):
+    """
+    A class representing a sketch animation event that progressively renders drawing operations.
+
+    This animation supports partial rendering of drawing and fill operations with configurable timing
+    and optional glowing dot effects. It allows for smooth, incremental visualization of drawing sequences.
+
+    Attributes:
+        wait_before_fill (float): Delay in seconds before starting fill animation, capped at half the total duration.
+
+    Methods:
+        get_partial_sketch: Calculates a partial OpsSet representing the current sketching progress.
+        apply: Applies the sketch animation to a given OpsSet at a specific progress point.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(AnimationEventType.CREATION, start_time, duration, easing_fun, data)
+        if data is None:
+            data = {}
+        self.wait_before_fill = data.get(
+            "wait_before_fill", 0
+        )  # seconds to wait before starting fill animation, if any
+        self.wait_before_fill = min(self.wait_before_fill, self.duration / 2)  # maximum wait is half of the duration
+
+    def get_partial_sketch(self, opsset: OpsSet, progress: float) -> OpsSet:
+        """
+        Calculate a partial OpsSet representing the sketching progress of an operation set.
+
+        Args:
+            OpsSet: The full drawn opsset on which to apply partial sketching
+            progress (float): The progress of sketching, ranging from 0.0 to 1.0.
+
+        Returns:
+            OpsSet: A new OpsSet containing the operations up to the specified progress point,
+                    with the last operation potentially being partially completed.
+        """
+        base_ops = opsset.opsset
+        draw_ops_count = 0  # number of opssets used for drawing
+        fill_ops_count = 0  # number of opssets used for filling
+        fill_mode = False
+        for op in base_ops:
+            if op.type not in Ops.SETUP_OPS_TYPES:
+                if fill_mode:
+                    fill_ops_count += 1
+                else:
+                    draw_ops_count += 1
+            elif op.type is OpsType.METADATA and op.data.get("drawing_mode") == "fill":
+                fill_mode = True
+        total_ops_count = draw_ops_count + fill_ops_count  # total count of drawing ops
+
+        # calculate per ops how much seconds is assigned
+        per_op_time = (self.duration - self.wait_before_fill) / total_ops_count
+
+        # calculate the drawing and filling times
+        draw_end_time = per_op_time * draw_ops_count
+        fill_start_time = draw_end_time + self.wait_before_fill
+
+        # based on progress, find out the total number of ops to be drawn
+        if progress * self.duration <= draw_end_time:
+            # drawing is not completed yet
+            draw_progress = progress * self.duration / draw_end_time
+            n_active = int(draw_progress * draw_ops_count)
+        elif progress * self.duration <= fill_start_time:
+            # drawing is completed, but filling is not started yet
+            n_active = draw_ops_count
+        else:
+            # filling is in progress
+            fill_progress = (progress * self.duration - fill_start_time) / (self.duration - fill_start_time)
+            n_active = draw_ops_count + int(fill_progress * fill_ops_count)
+
+        # create a new opsset with the partial ops
+        counter = 0
+        last_op = None
+        new_opsset = OpsSet(initial_set=[])  # initially start with blank opsset
+        for op in base_ops:
+            if op.type not in Ops.SETUP_OPS_TYPES and counter < n_active:
+                new_opsset.add(op)
+                counter += 1
+            elif counter < n_active:
+                # other operations keep adding, but don't increase counter
+                new_opsset.add(op)
+            else:
+                last_op = op  # the last operation for which it stopped
+                break
+        if last_op is not None and (progress * total_ops_count - n_active) > 0:
+            # need to calculate it partially
+            new_opsset.add(
+                Ops(
+                    type=last_op.type,
+                    data=last_op.data,
+                    partial=progress * total_ops_count - n_active,
+                )
+            )
+        return new_opsset
+
+    def _apply(self, opsset: OpsSet, progress: float):
+        """
+        Apply the sketch animation to an operation set with a given progress.
+
+        This method progressively renders the operations in the opsset based on the current animation progress,
+        with an optional glowing dot effect to highlight the current drawing point.
+
+        Args:
+            opsset (OpsSet): The set of operations to animate
+            progress (float): Animation progress from 0.0 to 1.0
+
+        Returns:
+            OpsSet: A new operation set with partially or fully rendered operations
+        """
+        new_opsset = OpsSet(initial_set=[])
+        if progress > 0:
+            sketching_opssets = self.get_partial_sketch(opsset, progress)
+            new_opsset.extend(sketching_opssets)
+            # now we can optionally add a glowing dot for the sketching operation
+            if self.data.get("glowing_dot") and progress < 1:
+                # the glowing dot should disappear at the end of the sketch
+                glow_dot_data = self.data.get("glowing_dot")
+                if not isinstance(glow_dot_data, dict):
+                    glow_dot_data = {}
+                # we need to draw glowing dot
+                cx, cy = sketching_opssets.get_current_point()  # get the current point based on sketching
+
+                breathing_factor = 1 + 0.05 * np.sin(
+                    2 * np.pi * progress * glow_dot_data.get("frequency", 5)
+                )  # have a subtle breathing effect to increase or decrease glow
+                dot = GlowDot(
+                    center=(cx, cy),
+                    radius=glow_dot_data.get("radius", 5) * breathing_factor,
+                    fill_style=FillStyle(color=glow_dot_data.get("color", (0.5, 0.5, 0.5))),
+                )
+                new_opsset.extend(dot.draw())  # add this dot at the end of current path
+        else:
+            # progress is 0, so nothing should be drawn
+            pass
+        return new_opsset

handanim/animations/translate.py

@@ -0,0 +1,66 @@
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import OpsSet
+
+
+class TranslateToAnimation(AnimationEvent):
+    """
+    A class representing a translate to a point animation event.
+
+    This animation translates an OpsSet from its current center of gravity to a specified point
+    over the course of the animation's duration, using an optional easing function.
+
+    Args:
+        start_time (float, optional): The start time of the animation. Defaults to 0.
+        duration (float, optional): The duration of the animation. Defaults to 0.
+        easing_fun (callable, optional): An optional easing function to modify animation progress. Defaults to None.
+        data (dict, optional): A dictionary containing animation data, including the target 'point'. Defaults to None.
+
+    Methods:
+        _opsset_apply: Calculates and applies the translation of the OpsSet.
+        apply: Applies the translation to the given OpsSet at the specified progress.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(
+            AnimationEventType.MUTATION, start_time, duration, easing_fun, data
+        )
+
+    def _opsset_apply(self, opsset: OpsSet, progress: float):
+        new_opsset = OpsSet(initial_set=opsset.opsset)
+        # calculate the center of gravity for the opsset
+        gravity_x, gravity_y = opsset.get_center_of_gravity()
+        point_x, point_y = self.data.get("point", (0, 0))
+        cur_x, cur_y = (
+            progress * point_x + (1 - progress) * gravity_x,
+            progress * point_y + (1 - progress) * gravity_y,
+        )
+        new_opsset.translate(cur_x - gravity_x, cur_y - gravity_y)
+        return new_opsset
+
+    def _apply(self, opsset: OpsSet, progress: float):
+        return self._opsset_apply(opsset, progress)
+
+class TranslateFromAnimation(TranslateToAnimation):
+    """
+    A class representing a translate from a point animation event.
+
+    This animation translates an OpsSet from a specified point to its current center of gravity
+    over the course of the animation's duration, using an optional easing function.
+
+    Inherits from TranslateToAnimation and reverses the progress to achieve the "from" translation effect.
+
+    Args:
+        start_time (float, optional): The start time of the animation. Defaults to 0.
+        duration (float, optional): The duration of the animation. Defaults to 0.
+        easing_fun (callable, optional): An optional easing function to modify animation progress. Defaults to None.
+        data (dict, optional): A dictionary containing animation data, including the starting 'point'. Defaults to None.
+
+    Methods:
+        apply: Applies the translation from the specified point to the OpsSet's center of gravity.
+    """
+
+    def __init__(self, start_time=0, duration=0, easing_fun=None, data=None):
+        super().__init__(start_time, duration, easing_fun, data)
+
+    def _apply(self, opsset, progress):
+        return super()._apply(opsset, 1 - progress)

handanim/animations/zoom.py

@@ -0,0 +1,52 @@
+from ..core.animation import AnimationEvent, AnimationEventType
+from ..core.draw_ops import OpsSet
+
+
+class ZoomInAnimation(AnimationEvent):
+    """
+    A class representing a zoom-in animation event that scales an OpsSet progressively.
+
+    This animation scales the operations set from its original size to a larger size
+    based on the provided progress value. It is typically used for creating or
+    expanding visual elements.
+
+    Args:
+        start_time (int, optional): The start time of the animation. Defaults to 0.
+        duration (int, optional): The duration of the animation. Defaults to 0.
+        easing_fun (callable, optional): An optional easing function to modify the animation progress. Defaults to None.
+        data (Any, optional): Additional data associated with the animation. Defaults to None.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(AnimationEventType.CREATION, start_time, duration, easing_fun, data)
+
+    def _apply_opsset(self, opsset: OpsSet, progress: float):
+        new_opsset = OpsSet(initial_set=opsset.opsset)
+        new_opsset.scale(progress)
+        return new_opsset
+
+    def _apply(self, opsset, progress):
+        return self._apply_opsset(opsset, progress)
+
+
+class ZoomOutAnimation(ZoomInAnimation):
+    """
+    A class representing a zoom-out animation event that scales an OpsSet progressively.
+
+    This animation scales the operations set from its current size to a smaller size
+    based on the provided progress value. It is typically used for shrinking or
+    removing visual elements.
+
+    Args:
+        start_time (int, optional): The start time of the animation. Defaults to 0.
+        duration (int, optional): The duration of the animation. Defaults to 0.
+        easing_fun (callable, optional): An optional easing function to modify the animation progress. Defaults to None.
+        data (Any, optional): Additional data associated with the animation. Defaults to None.
+    """
+
+    def __init__(self, start_time=0.0, duration=0.0, easing_fun=None, data=None):
+        super().__init__(start_time, duration, easing_fun, data)
+        self.type = AnimationEventType.DELETION
+
+    def _apply(self, opsset, progress):
+        return super()._apply(opsset, 1 - progress)

handanim/core/__init__.py

@@ -0,0 +1,16 @@
+from .animation import AnimationEvent, AnimationEventType, CompositeAnimationEvent
+from .drawable import Drawable, DrawableGroup
+from .scene import Scene
+from .styles import FillStyle, SketchStyle, StrokeStyle
+
+__all__ = [
+    "AnimationEvent",
+    "AnimationEventType",
+    "Scene",
+    "StrokeStyle",
+    "SketchStyle",
+    "FillStyle",
+    "Drawable",
+    "DrawableGroup",
+    "CompositeAnimationEvent",
+]