Layer class¶

def refresh(self) -> None:
    """Refreshes the layer data."""
    super().refresh()
    if not self.refresh_on_call and self._data:
        return

    try:
        self._data = george.tv_layer_info(self._id)
    except GeorgeError:
        self.mark_removed()
        self.refresh()

@george.min_version_compatible(min_version="12")
def set_folder_position(self, folder: LayerFolder, position: int) -> None:
    """Moves the layer to the provided position in the folder.

    Note:
        the position is relative to the root of the layer stack and not the folder.
        If the position is larger than that of the last layer in the folder, then the layer will be placed last.
        If you want to move a layer outside it's folder then just set its position using the layer.position property
        and move it outside the range of the folder, meaning before the first or after the last layer in the folder.
    """
    value = max(0, position)
    # TVPaint will always set the position at (value - 1) if value is superior to 0, so we need to add +1 in
    #  that case to set the position correctly, I don't know why it works this way, but it honestly makes no sense
    if value != 0:
        value += 1

    self.make_current()
    george.tv_layer_move(value, folder.id)

@name.setter
@set_as_current
def name(self, value: str) -> None:
    """Set the layer name.

    Note:
        it uses `get_unique_name` to find a unique layer name across all the layers in the clip
    """
    if value == self.name:
        return

    layer_names = (layer.name for layer in self.clip.get_layers() if layer != self)
    value = utils.get_unique_name(layer_names, value)
    george.tv_layer_rename(self.id, value)

@refreshed_property
def layer_type(self) -> george.LayerType:
    """The layer type."""
    return self._data.type

@refreshed_property
def start(self) -> int:
    """The layer start frame according to the project's start frame."""
    return self._data.first_frame + self.project.start_frame

@refreshed_property
def end(self) -> int:
    """The layer end frame according to the project's start frame."""
    return self._data.last_frame + self.project.start_frame

def make_current(self) -> None:
    """Make the layer current, it also makes the clip current."""
    if self.is_current:
        return
    if self.clip:
        self.clip.make_current()
    george.tv_layer_set(self.id)

@set_as_current
def convert_to_anim_layer(self) -> None:
    """Converts the layer to an animation layer."""
    george.tv_layer_anim(self.id)

def load_dependencies(self) -> None:
    """Load all dependencies of the layer in memory."""
    george.tv_layer_load_dependencies(self.id)

@staticmethod
def current_layer_id() -> int:
    """Returns the current layer id."""
    return george.tv_layer_current_id()

@classmethod
def current_layer(cls) -> Layer:
    """Returns the current layer object."""
    from pytvpaint.clip import Clip

    return cls(layer_id=cls.current_layer_id(), clip=Clip.current_clip())

@set_as_current
def shift(self, new_start: int) -> None:
    """Move the layer to a new frame."""
    george.tv_layer_shift(self.id, new_start - self.project.start_frame)

@set_as_current
def merge(
    self,
    layer: Layer,
    blending_mode: george.BlendingMode,
    stamp: bool = False,
    erase: bool = False,
    keep_color_grp: bool = True,
    keep_img_mark: bool = True,
    keep_instance_name: bool = True,
) -> None:
    """Merge this layer with the given one.

    Args:
        layer: the layer to merge with
        blending_mode: the blending mode to use
        stamp: Use stamp mode
        erase: Remove the source layer
        keep_color_grp: Keep the color group
        keep_img_mark: Keep the image mark
        keep_instance_name: Keep the instance name
    """
    george.tv_layer_merge(
        layer.id,
        blending_mode,
        stamp,
        erase,
        keep_color_grp,
        keep_img_mark,
        keep_instance_name,
    )

@staticmethod
def merge_all(
    keep_color_grp: bool = True,
    keep_img_mark: bool = True,
    keep_instance_name: bool = True,
) -> None:
    """Merge all the layers in the stack.

    Args:
        keep_color_grp: Keep the color group
        keep_img_mark: Keep the image mark
        keep_instance_name: Keep the instance name
    """
    george.tv_layer_merge_all(keep_color_grp, keep_img_mark, keep_instance_name)

@classmethod
@george.undoable
def new(
    cls,
    name: str,
    clip: Clip | None = None,
    color: LayerColor | None = None,
) -> Layer:
    """Create a new layer.

    Args:
        name: the name of the new layer
        clip: the parent clip
        color: the layer color

    Returns:
        Layer: the new layer

    Note:
        The layer name is checked against all other layers to have a unique name using `get_unique_name`.
        This can take a while if you have a lot of layers.
    """
    from pytvpaint.clip import Clip

    clip = clip or Clip.current_clip()
    clip.make_current()

    name = utils.get_unique_name(clip.layer_names, name)
    layer_type = 1 if cls == Layer else 0
    layer_id = george.tv_layer_create(name, layer_type=layer_type)

    layer = cls(layer_id=layer_id, clip=clip)
    if color:
        layer.color = color

    return layer

@classmethod
@george.undoable
def new_anim_layer(
    cls,
    name: str,
    clip: Clip | None = None,
    color: LayerColor | None = None,
) -> Layer:
    """Create a new animation layer.

    Args:
        name: the name of the new layer
        clip: the parent clip
        color: the layer color

    Returns:
        Layer: the new animation layer

    Note:
        It activates the thumbnail visibility
    """
    layer = cls.new(name, clip, color)
    layer.convert_to_anim_layer()
    layer.thumbnails_visible = True
    return layer

@classmethod
@george.undoable
def new_background_layer(
    cls,
    name: str,
    clip: Clip | None = None,
    color: LayerColor | None = None,
    image: Path | str | None = None,
    stretch: bool = False,
) -> Layer:
    """Create a new background layer with hold as pre- and post-behavior.

    Args:
        name: the name of the new layer
        clip: the parent clip
        color: the layer color
        image: the background image to load
        stretch: whether to stretch the image to fit the view

    Returns:
        Layer: the new animation layer
    """
    from pytvpaint.clip import Clip

    clip = clip or Clip.current_clip()
    layer = cls.new(name, clip, color)
    layer.pre_behavior = george.LayerBehavior.HOLD
    layer.post_behavior = george.LayerBehavior.HOLD
    layer.thumbnails_visible = True

    image = Path(image or "")
    if image.is_file():
        layer.convert_to_anim_layer()
        layer.load_image(image, frame=clip.start, stretch=stretch)

    return layer

@set_as_current
@george.undoable
def duplicate(self, name: str) -> Layer:
    """Duplicate this layer.

    Args:
        name: the duplicated layer name

    Returns:
        Layer: the duplicated layer
    """
    name = utils.get_unique_name(self.clip.layer_names, name)
    layer_id = george.tv_layer_duplicate(name)

    return Layer(layer_id=layer_id, clip=self.clip)

def remove(self) -> None:
    """Remove the layer from the clip.

    Warning:
        The current instance won't be usable after this call since it will be mark removed.
    """
    self.clip.make_current()
    self.is_locked = False
    george.tv_layer_kill(self.id)
    self.mark_removed()

@set_as_current
def render(
    self,
    output_path: Path | str | FileSequence,
    start: int | None = None,
    end: int | None = None,
    frame_set: FrameSet | None = None,
    use_camera: bool = False,
    alpha_mode: george.AlphaSaveMode = george.AlphaSaveMode.PREMULTIPLY,
    background_mode: george.BackgroundMode | None = None,
    format_opts: list[str] | None = None,
) -> Path | FileSequence:
    """Render the layer to a single frame or frame sequence or movie.

    Args:
        output_path: a single file or file sequence pattern
        start: the start frame to render the layer's start if None. Defaults to None.
        end: the end frame to render or the layer's end if None. Defaults to None.
        frame_set: a FrameSet with the frames/range to render. Defaults to None.
        use_camera: use the camera for rendering, otherwise render the whole canvas. Defaults to False.
        alpha_mode: the alpha mode for rendering. Defaults to george.AlphaSaveMode.PREMULTIPLY.
        background_mode: the background mode for rendering. Defaults to None.
        format_opts: custom format options. Defaults to None.

    Raises:
        ValueError: if requested range (start-end) not in clip range/bounds
        ValueError: if output is a movie
        FileNotFoundError: if the render failed and no files were found on disk or missing frames

    Note:
        This functions uses the layer's range as a basis (start-end). This  is different from a project range, which
        uses the project timeline. For more details on the differences in frame ranges and the timeline in TVPaint,
        please check the `Usage/Rendering` section of the documentation.

    Warning:
        Even tough pytvpaint does a pretty good job of correcting the frame ranges for rendering, we're still
        encountering some weird edge cases where TVPaint will consider the range invalid for seemingly no reason.

    Returns:
        the output file path or sequence
    """
    start = self.start if start is None else start
    end = self.end if end is None else end
    frame_set = frame_set or FrameSet(f"{start}-{end}")
    return self.clip.render(
        output_path=output_path,
        frame_set=frame_set,
        use_camera=use_camera,
        layer_selection=[self],
        alpha_mode=alpha_mode,
        background_mode=background_mode,
        format_opts=format_opts,
    )

@set_as_current
def render_frame(
    self,
    export_path: Path | str,
    frame: int | None = None,
    alpha_mode: george.AlphaSaveMode = george.AlphaSaveMode.PREMULTIPLY,
    background_mode: george.BackgroundMode | None = george.BackgroundMode.NONE,
    format_opts: list[str] | None = None,
    use_camera: bool = False,
) -> Path:
    """Render a frame from the layer.

    Args:
        export_path: the frame export path (the extension determines the output format)
        frame: the frame to render or the current frame if None. Defaults to None.
        alpha_mode: the render alpha mode
        background_mode: the render background mode
        format_opts: custom output format options to pass when rendering
        use_camera: use the camera for rendering, otherwise render the whole canvas. Defaults to False.

    Raises:
        FileNotFoundError: if the render failed or output not found on disk

    Returns:
        Path: render output path
    """
    export_path = Path(export_path)
    frame = frame or self.clip.current_frame
    self.clip.current_frame = frame

    self.clip.render(
        output_path=export_path,
        frame_set=FrameSet(frame),
        use_camera=use_camera,
        layer_selection=[self],
        alpha_mode=alpha_mode,
        background_mode=background_mode,
        format_opts=format_opts,
    )
    return Path(export_path)

@set_as_current
def render_instances(
    self,
    export_path: Path | str | FileSequence,
    frame_set: FrameSet | None = None,
    alpha_mode: george.AlphaSaveMode = george.AlphaSaveMode.PREMULTIPLY,
    background_mode: george.BackgroundMode | None = None,
    format_opts: list[str] | None = None,
    use_camera: bool = False,
) -> Path | FileSequence:
    """Render all layer instances in the provided range for the current layer.

    Args:
        export_path: the export path (the extension determines the output format)
        frame_set: Render only the instances within the provided frameset. Defaults to None.
        alpha_mode: the render alpha mode
        background_mode: the render background mode
        format_opts: custom output format options to pass when rendering
        use_camera: use the camera for rendering, otherwise render the whole canvas. Defaults to False.

    Raises:
        ValueError: if requested range (start-end) not in layer range/bounds
        ValueError: if output is a movie
        FileNotFoundError: if the render failed or output not found on disk

    Returns:
        FileSequence: instances output sequence
    """
    frames = sorted([layer_instance.start for layer_instance in self.instances])
    if frame_set is not None:
        frame_set = FrameSet([f for f in frame_set.items if f in frames])
    else:
        frame_set = FrameSet(frames) or frame_set

    return self.clip.render(
        output_path=export_path,
        frame_set=frame_set,
        use_camera=use_camera,
        layer_selection=[self],
        alpha_mode=alpha_mode,
        background_mode=background_mode,
        format_opts=format_opts,
    )

@set_as_current
def load_image(self, image_path: str | Path, frame: int | None = None, stretch: bool = False) -> None:
    """Load an image in the current layer at a given frame.

    Args:
        image_path: path to the image to load
        frame: the frame where the image will be loaded, if none provided, image will be loaded at current frame
        stretch: whether to stretch the image to fit the view

    Raises:
        FileNotFoundError: if the file doesn't exist at provided path
    """
    image_path = Path(image_path)
    if not image_path.exists():
        raise FileNotFoundError(f"Image not found at : {image_path}")

    frame = frame or self.clip.current_frame
    with utils.restore_current_frame(self.clip, frame):
        # if no instance at the specified frame, then create a new one
        if not self.get_instance(frame):
            self.add_instance(frame)

        george.tv_load_image(image_path.as_posix(), stretch)

def get_mark_color(self, frame: int) -> LayerColor | None:
    """Get the mark color at a specific frame.

    Args:
        frame: frame with a mark

    Returns:
        LayerColor | None: the layer color if there was a mark
    """
    frame = frame - self.project.start_frame
    color_index = george.tv_layer_mark_get(self.id, frame)
    if not color_index:
        return None

    return self.clip.get_layer_color(by_index=color_index)

def add_mark(self, frame: int, color: LayerColor) -> None:
    """Add a mark to a frame.

    Args:
        frame: frame to put a mark on
        color: the color index

    Raises:
        TypeError: if the layer is not an animation layer
    """
    if not self.is_anim_layer:
        raise TypeError(f"Can't add a mark because this is not an animation layer ({self})")
    frame = frame - self.project.start_frame
    george.tv_layer_mark_set(self.id, frame, color.index)

def remove_mark(self, frame: int) -> None:
    """Remove a mark.

    Args:
        frame: a frame number with a mark
    """
    # Setting it at 0 clears the mark
    self.add_mark(frame, LayerColor(0, self.clip))

def clear_marks(self) -> None:
    """Clear all the marks in the layer."""
    for frame, _ in self.marks:
        self.remove_mark(frame)

@set_as_current
def pan(self, position: tuple[int, int], move_fill: bool = False, anti_aliasing: bool = False) -> None:
    """Apply a panning FX to the current layer.

    Args:
        position: new position of the layer (position is calculated from the top left corner of the layer frame)
        move_fill: True to moved and fill all screen, False to only move images
        anti_aliasing: apply antialiasing
    """
    george.tv_panning(position[0], position[1], move_fill, anti_aliasing)

@set_as_current
def select_frames(self, start: int, end: int) -> None:
    """Select the frames from a start and count.

    Args:
        start: the selection start frame
        end: the selected end frame
    """
    if not self.is_anim_layer:
        log.warning("Selection may display weird behaviour when applied to a non animation layer")
    frame_count = (end - start) + 1
    george.tv_layer_select(start - self.clip.start, frame_count)

@set_as_current
def select_all_frames(self) -> None:
    """Select all frames in the layer."""
    frame, frame_count = george.tv_layer_select_info(full=True)
    george.tv_layer_select(frame, frame_count)

@set_as_current
def clear_selection(self) -> None:
    """Clear frame selection in the layer."""
    # selecting frames after the layer's end frame will result in a empty selection, thereby clearing the selection
    george.tv_layer_select(self.end + 1, 0)

@set_as_current
def cut_selection(self) -> None:
    """Cut the selected instances."""
    george.tv_layer_cut()

@set_as_current
def copy_selection(self) -> None:
    """Copy the selected instances."""
    george.tv_layer_copy()

def paste_selection(self, target_layer: Layer | None = None) -> None:
    """Paste the layer into another layer (regardless of the project)."""
    if target_layer:
        target_layer.make_current()
    george.tv_layer_paste()

@set_as_current
def cut(self) -> None:
    """Copy the layer (cuts all instances in layer)."""
    self.select_all_frames()
    self.cut_selection()

@set_as_current
def copy(self) -> None:
    """Copy the layer (copies all instances in layer)."""
    self.select_all_frames()
    self.copy_selection()

@set_as_current
def paste(self) -> None:
    """Copy the layer (copies all instances in layer)."""
    self.select_all_frames()
    self.paste_selection()

@refreshed_property
@set_as_current
def instances(self) -> Iterator[LayerInstance]:
    """Iterates over the layer instances.

    Yields:
        each LayerInstance present in the layer
    """
    # instances start at layer start
    current_instance = LayerInstance(self, self.start)

    while True:
        yield current_instance

        nex_instance = current_instance.next
        if nex_instance is None:
            break

        current_instance = nex_instance

def get_instance(self, frame: int, strict: bool = False) -> LayerInstance | None:
    """Get the instance at that frame.

    Args:
        frame: the instance frame
        strict: True will only return Instance if the given frame is the start of the instance. Default is False

    Returns:
        the instance if found else None
    """
    for layer_instance in self.instances:
        if strict:
            if layer_instance.start != frame:
                continue
            return layer_instance

        if not (layer_instance.start <= frame <= layer_instance.end):
            continue
        return layer_instance

    return None

def get_instances(self, from_frame: int, to_frame: int) -> Iterator[LayerInstance]:
    """Iterates over the layer instances and returns the one in the range (from_frame-to_frame).

    Yields:
        each LayerInstance in the range (from_frame-to_frame)
    """
    for layer_instance in self.instances:
        if layer_instance.end < from_frame:
            continue
        if from_frame <= layer_instance.start <= to_frame:
            yield layer_instance
        if layer_instance.start > to_frame:
            break

@set_as_current
def add_instance(
    self,
    start: int | None = None,
    nb_frames: int = 1,
    direction: george.InsertDirection | None = None,
    split: bool = False,
) -> LayerInstance:
    """Crates a new instance.

    Args:
        start: start frame. Defaults to clip current frame if none provided
        nb_frames: number of frames in the new instance. Default is 1, this is the total number of frames created.
        direction: direction where new frames will be added/inserted
        split: True to make each added frame a new image

    Raises:
        TypeError: if the layer is not an animation layer
        ValueError: if the number of frames `nb_frames` is inferior or equal to 0
        ValueError: if an instance already exists at the given range (start + nb_frames)

    Returns:
        LayerInstance: new layer instance
    """
    if not self.is_anim_layer:
        raise TypeError("The layer needs to be an animation layer")

    if nb_frames <= 0:
        raise ValueError("Instance number of frames must be at least 1")

    if start and self.get_instance(start):
        raise ValueError(
            "An instance already exists at the designated frame range. Edit or delete it before adding a new one."
        )

    start = start if start is not None else self.clip.current_frame
    self.clip.make_current()

    temp_layer = Layer.new_anim_layer(str(uuid4()))
    temp_layer.make_current()

    with utils.restore_current_frame(self.clip, 1):
        if nb_frames > 1:
            if split:
                george.tv_layer_insert_image(count=nb_frames, direction=direction)
            else:
                layer_instance = next(temp_layer.instances)
                layer_instance.length = nb_frames

        temp_layer.select_all_frames()
        temp_layer.copy_selection()
        self.clip.current_frame = start
        self.make_current()
        self.paste_selection()
        temp_layer.remove()

    return LayerInstance(self, start)

def rename_instances(
    self,
    mode: george.InstanceNamingMode,
    prefix: str | None = None,
    suffix: str | None = None,
    process: george.InstanceNamingProcess | None = None,
) -> None:
    """Rename all the instances.

    Args:
        mode: the instance renaming mode
        prefix: the prefix to add to each name
        suffix: the suffix to add to each name
        process: the instance naming process
    """
    george.tv_instance_name(self.id, mode, prefix, suffix, process)

def mark_removed(self) -> None:
    """Marks the object as removed and is therefor not usable."""
    self._is_removed = True