Layer related George functions¶

def tv_layer_current_id() -> int:
    """Get the id of the current layer."""
    return int(send_cmd("tv_LayerCurrentId"))

@try_cmd(exception_msg="No layer at provided position")
def tv_layer_get_id(position: int) -> int:
    """Get the id of the layer at the given position.

    Raises:
        GeorgeError: if no layer found at the provided position
    """
    result = send_cmd("tv_LayerGetID", position, error_values=[GrgErrorValue.NONE])
    return int(result)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_get_pos(layer_id: int) -> int:
    """Get the position of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    return int(send_cmd("tv_LayerGetPos", layer_id, error_values=[GrgErrorValue.NONE]))

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_info(layer_id: int) -> TVPLayer:
    """Get information of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    result = send_cmd("tv_LayerInfo", layer_id, error_values=[GrgErrorValue.EMPTY])
    layer = tv_parse_list(result, with_fields=TVPLayer, unused_indices=[7, 8])
    layer["id"] = layer_id
    return TVPLayer(**layer)

@try_cmd(exception_msg="Couldn't move current layer to position")
def tv_layer_move(position: int, folder_id: int | None = None) -> None:
    """Move the current layer to a new position in the layer stack.

    Args:
        position: position to move layer to
        folder_id: parent folder id

    Raises:
        GeorgeError: if layer could not be moved
    """
    if folder_id is not None and is_tvp_version_below_12():
        log.warning("`folder_id` option is only available in TVPaint version 12 and above.")

    args = [position]
    if not is_tvp_version_below_12() and folder_id:
        args.append(folder_id)

    send_cmd("tv_LayerMove", *args)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_set(layer_id: int) -> None:
    """Make the given layer the current one.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerSet", layer_id)

@try_cmd(raise_exc=NoObjectWithIdError, exception_msg="Invalid layer id")
def tv_layer_selection_get(layer_id: int) -> bool:
    """Get the selection state of a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerSelection", layer_id, error_values=[-1])
    return tv_cast_to_type(res, bool)

@try_cmd(raise_exc=NoObjectWithIdError, exception_msg="Invalid layer id")
def tv_layer_selection_set(layer_id: int, new_state: bool) -> None:
    """Set the selection state of a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerSelection", layer_id, int(new_state), error_values=[-1])

def tv_layer_select(start_frame: int, frame_count: int) -> int:
    """Select frames in the current layer.

    Args:
        start_frame: selection start
        frame_count: number of frames to select

    Returns:
        int: number of frames selected

    Note:
        If the start position is before the beginning of the layer, the selection will only start at the beginning of
        the layer, but its length will be measured from the start position.
        This means that if you ask for a selection of 15 frames starting from position 0 in a layer that actually
        starts at position 5, only the first 10 frames in the layer will be selected.
        If the selection goes beyond the end of the layer, it will only include the frames between the start and end of
        the layer. No frames will be selected if the start position is beyond the end of the layer
    """
    return int(send_cmd("tv_LayerSelect", start_frame, frame_count, error_values=[-1]))

def tv_layer_select_info(full: bool = False) -> tuple[int, int]:
    """Get Selected frames in a layer.

    Args:
        full:  returns the layers full range (from the first to the last instance), even on a non anim/ctg layer

    Returns:
        frame: the start frame of the selection. If full is set to True will return the first frame in the layer
        count: the number of frames in the selection. If full is set to True will return the number of frames in the layer

    Bug:
        The official documentation states that this functions selects the layer frames, it does not, it simply
        returns the frames selected. This will also return all frames in the layer even if they are not selected if the
        argument `full` is set to True. We advise using `tv_layer_select` to select your frames and only using this
        function to get the selected frames.
    """
    args = ["full"] if full else []
    res = send_cmd("tv_layerSelectInfo", *args)
    frame, count = tuple(map(int, res.split(" ")))
    return frame, count

def tv_layer_create(name: str, layer_type: int = 1) -> int:
    """Create a new image layer with the given name.

    Args:
        name: layer name
        layer_type: 1 for normal layer, 0 for Folder layer (only available for TVPaint 12 and above)

    Returns:
        layer_id: the id of the newly created layer.
    """
    if layer_type != 1 and is_tvp_version_below_12():
        log.warning("`layer_type` selection is only available in TVPaint version 12 and above.")

    args = [name]
    if not is_tvp_version_below_12():
        args.append(str(layer_type))
        if not name:
            log.warning(
                "You should provide a name for the layer, "
                "otherwise tvpaint will consider that the layer type is the name."
            )

    return int(send_cmd("tv_LayerCreate", *args))

def tv_layer_duplicate(name: str) -> int:
    """Duplicate the current layer and make it the current one."""
    return int(send_cmd("tv_LayerDuplicate", name))

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_rename(layer_id: int, name: str) -> str:
    """Rename a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id.

    Warning:
        This function does not seem to work in TVPaint 12.

    Returns:
        str: new name
    """
    if not is_tvp_version_below_12():
        log.warning("function `tv_LayerRename` does not seem to work properly in TVPaint 12")
    return send_cmd("tv_LayerRename", layer_id, name, error_values=[-1])

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_kill(layer_id: int) -> None:
    """Delete the layer with provided id.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerKill", layer_id)

@min_version_compatible(min_version="12")
@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_folder_delete(layer_id: int, remove_children: bool) -> None:
    """Delete the layer with provided id.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
        NotImplemented: if used in tvpaint version inferior to 12
    """
    send_cmd("tv_LayerFolderDelete", layer_id, int(not remove_children))

def tv_layer_density_get() -> int:
    """Get the current layer density (opacity)."""
    return int(send_cmd("tv_LayerDensity"))

def tv_layer_density_set(new_density: int) -> None:
    """Set the current layer density (opacity ranging from 0 to 100)."""
    send_cmd("tv_LayerDensity", new_density)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_display_get(layer_id: int) -> bool:
    """Get the visibility of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerDisplay", layer_id, error_values=[0])
    return tv_cast_to_type(res.lower(), bool)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_display_set(layer_id: int, new_state: bool, light_table: bool = False) -> None:
    """Set the visibility of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    args: list[Any] = [layer_id, int(new_state)]
    if light_table:
        args.insert(1, "lighttable")
    send_cmd("tv_LayerDisplay", *args, error_values=[0])

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_lock_get(layer_id: int) -> bool:
    """Get the lock state of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerLock", layer_id, error_values=[GrgErrorValue.ERROR])
    return tv_cast_to_type(res.lower(), bool)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_lock_set(layer_id: int, new_state: bool) -> None:
    """Set the lock state of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd(
        "tv_LayerLock",
        layer_id,
        int(new_state),
        error_values=[GrgErrorValue.ERROR],
    )

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_collapse_get(layer_id: int) -> bool:
    """Get the collapse mode of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    return bool(int(send_cmd("tv_LayerCollapse", layer_id, error_values=[-2])))

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_collapse_set(layer_id: int, new_state: bool) -> None:
    """Set the collapse mode of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerCollapse", layer_id, int(new_state), error_values=[-2])

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_blending_mode_get(layer_id: int) -> BlendingMode:
    """Get the blending mode of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerBlendingMode", layer_id)
    return tv_cast_to_type(res.lower(), BlendingMode)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_blending_mode_set(layer_id: int, mode: BlendingMode) -> None:
    """Set the blending mode of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerBlendingMode", layer_id, mode.value)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_stencil_get(layer_id: int) -> StencilMode:
    """Get the stencil state and mode of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerStencil", layer_id)
    _, state, mode = res.split(" ")

    if state == "off":
        return StencilMode.OFF

    return tv_cast_to_type(mode, StencilMode)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_stencil_set(layer_id: int, mode: StencilMode) -> None:
    """Set the stencil state and mode of the given layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    args = [mode.value] if mode in [StencilMode.ON, StencilMode.OFF] else ["on", mode.value]

    send_cmd("tv_LayerStencil", layer_id, *args)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_show_thumbnails_get(
    layer_id: int,
) -> bool:
    """Get the show thumbnails state for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerShowThumbnails", layer_id, error_values=[GrgErrorValue.ERROR])
    return res == "1"

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_show_thumbnails_set(
    layer_id: int,
    state: bool,
) -> None:
    """Set the show thumbnail state for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd(
        "tv_LayerShowThumbnails",
        layer_id,
        int(state),
        error_values=[GrgErrorValue.ERROR],
    )

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_auto_break_instance_get(layer_id: int) -> bool:
    """Get the layer auto break instance value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerAutoBreakInstance", layer_id, error_values=[-1, -2, -3])
    return res == "1"

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_auto_break_instance_set(
    layer_id: int,
    state: bool,
) -> None:
    """Set the layer auto break instance value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd(
        "tv_LayerAutoBreakInstance",
        layer_id,
        int(state),
        error_values=[-1, -2, -3],
    )

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_auto_create_instance_get(
    layer_id: int,
) -> bool:
    """Get the layer auto create instance value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerAutoCreateInstance", layer_id, error_values=[-1, -2, -3])
    return res == "1"

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_auto_create_instance_set(
    layer_id: int,
    state: bool,
) -> None:
    """Set the layer auto create instance value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerAutoCreateInstance", layer_id, int(state), error_values=[-1, -2, -3])

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_pre_behavior_get(layer_id: int) -> LayerBehavior:
    """Get the pre-behavior value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerPreBehavior", layer_id)
    return tv_cast_to_type(res, LayerBehavior)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_pre_behavior_set(layer_id: int, behavior: LayerBehavior) -> None:
    """Set the pre-behavior value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerPreBehavior", layer_id, behavior.value)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_post_behavior_get(layer_id: int) -> LayerBehavior:
    """Get the post-behavior value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerPostBehavior", layer_id)
    return tv_cast_to_type(res, LayerBehavior)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_post_behavior_set(layer_id: int, behavior: LayerBehavior) -> None:
    """Set the post-behavior value for a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerPostBehavior", layer_id, behavior.value)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_lock_position_get(layer_id: int) -> bool:
    """Get the lock position state of a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd("tv_LayerLockPosition", layer_id)
    return tv_cast_to_type(res, bool)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_lock_position_set(layer_id: int, state: bool) -> None:
    """Set the lock position state of a layer.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerLockPosition", layer_id, int(state))

def tv_preserve_get() -> LayerTransparency:
    """Get the preserve transparency state of the current layer."""
    res = send_cmd("tv_Preserve")
    _, state = res.split(" ")
    return tv_cast_to_type(state, LayerTransparency)

def tv_preserve_set(state: LayerTransparency) -> None:
    """Set the preserve transparency state of the current layer.

    Warning:
        This function does not seem to work in TVPaint 12
    """
    if not is_tvp_version_below_12():
        log.warning("This function does not seem to work in TVPaint 12")
    send_cmd("tv_Preserve", "alpha", state.value)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_mark_get(layer_id: int, frame: int) -> int:
    """Get the mark color of a layer at a frame.

    Args:
        layer_id: the layer id
        frame: the frame with a mark

    Raises:
        NoObjectWithIdError: if given an invalid layer id

    Returns:
        int: the mark color index
    """
    res = send_cmd("tv_LayerMarkGet", layer_id, frame, error_values=[-1])
    if is_tvp_version_below_12():
        return int(res)

    index, _, _, _ = tv_cast_to_type(res, tuple[int, ...])
    return index

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_mark_set(layer_id: int, frame: int, color_index: int) -> None:
    """Set the mark of the layer's frame.

    Args:
        layer_id: the layer id
        frame: the frame to set the mark (use 0 to remove it).
        color_index: the mark color

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerMarkSet", layer_id, frame, color_index)

def tv_layer_anim(layer_id: int) -> None:
    """Convert the layer to an anim layer."""
    send_cmd("tv_LayerAnim", *([layer_id] if layer_id else []))

def tv_layer_copy() -> None:
    """Copy the current image or the selected ones."""
    send_cmd("tv_LayerCopy")

def tv_layer_cut() -> None:
    """Cut the current image or the selected ones."""
    send_cmd("tv_LayerCut")

def tv_layer_paste() -> None:
    """Paste the previously copied/cut images to the current layer."""
    send_cmd("tv_LayerPaste")

def tv_layer_insert_image(
    count: int = 1,
    direction: InsertDirection | None = None,
    duplicate: bool | None = None,
) -> None:
    """Add new image(s) before/after the current one and make it current."""
    if duplicate:
        args = [0]
    else:
        args_dict = {
            "count": count,
            "direction": direction.value if direction is not None else None,
        }
        args = args_dict_to_list(args_dict)

    send_cmd("tv_LayerInsertImage", *args)

def tv_layer_merge(
    layer_id: int,
    blending_mode: BlendingMode,
    stamp: bool = False,
    erase: bool = False,
    keep_color_grp: bool = True,
    keep_img_mark: bool = True,
    keep_instance_name: bool = True,
) -> None:
    """Merge the given layer with the current one.

    Args:
        layer_id: the layer id
        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
    """
    args = [
        layer_id,
        blending_mode.value,
    ]

    if stamp:
        args.append("stamp")
    if erase:
        args.append("erase")

    args_dict = {
        "keepcolorgroup": int(keep_color_grp),
        "keepimagemark": int(keep_img_mark),
        "keepinstancename": int(keep_instance_name),
    }
    args.extend(args_dict_to_list(args_dict))

    send_cmd("tv_LayerMerge", layer_id, *args)

def tv_layer_merge_all(
    keep_color_grp: bool = True,
    keep_img_mark: bool = True,
    keep_instance_name: bool = True,
) -> None:
    """Merge all layers.

    Args:
        keep_color_grp: Keep the color group
        keep_img_mark: Keep the image mark
        keep_instance_name: Keep the instance name
    """
    args_dict = {
        "keepcolorgroup": int(keep_color_grp),
        "keepimagemark": int(keep_img_mark),
        "keepinstancename": int(keep_instance_name),
    }
    send_cmd("tv_LayerMergeAll", *args_dict_to_list(args_dict))

def tv_layer_shift(layer_id: int, start: int) -> None:
    """Move the layer to a new frame.

    Args:
        layer_id: layer id
        start: frame to shift layer to
    """
    send_cmd("tv_LayerShift", layer_id, start)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_load_dependencies(layer_id: int) -> None:
    """Load all dependencies of the given layer in memory.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd("tv_LayerLoadDependencies", layer_id)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_color_get_color(clip_id: int, color_index: int) -> TVPClipLayerColor:
    """Get a specific colors information in the clips color list.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    result = send_cmd(
        "tv_LayerColor",
        LayerColorAction.GETCOLOR.value,
        clip_id,
        color_index,
        error_values=[GrgErrorValue.ERROR, -1, -2],
    )
    parsed = tv_parse_list(result, with_fields=TVPClipLayerColor)
    return TVPClipLayerColor(**parsed)

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_color_set_color(
    clip_id: int,
    color_index: int,
    color: RGBColor,
    name: str | None = None,
) -> None:
    """Set a specific colors information in the clips color list.

    Raises:
        NoObjectWithIdError: if given an invalid layer id

    Warning:
        In tvpaint 12, this function will fail when the `name` argument is provided

    Note:
        The color with index 0 is the "Default" color, and it can't be changed
    """
    args: list[Any] = [
        LayerColorAction.SETCOLOR.value,
        clip_id,
        color_index,
        color.r,
        color.g,
        color.b,
    ]

    if name:
        if not is_tvp_version_below_12():
            log.warning("In tvpaint 12, this function will fail when the `name` argument is provided")
        args.append(name)

    send_cmd("tv_LayerColor", *args, error_values=[GrgErrorValue.ERROR])

@try_cmd(
    raise_exc=NoObjectWithIdError,
    exception_msg="Invalid layer id",
)
def tv_layer_color_get(layer_id: int) -> int:
    """Get the layer's color index from the clips color list.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    res = send_cmd(
        "tv_LayerColor",
        LayerColorAction.GET.value,
        layer_id,
        error_values=[-1],
    )
    if is_tvp_version_below_12():
        return int(res)

    index, _, _, _ = tv_cast_to_type(res, tuple[int, ...])
    return index

@try_cmd(raise_exc=NoObjectWithIdError)
def tv_layer_color_set(layer_id: int, color_index: int) -> None:
    """Set the layer's color index from the clips color list.

    Raises:
        NoObjectWithIdError: if given an invalid layer id
    """
    send_cmd(
        "tv_LayerColor",
        LayerColorAction.SET.value,
        layer_id,
        color_index,
        error_values=[-1],
    )

def tv_layer_color_lock(color_index: int) -> int:
    """Lock all layers that use the given color index.

    Args:
        color_index: the layer color index

    Returns:
        the number of layers locked
    """
    return int(send_cmd("tv_LayerColor", LayerColorAction.LOCK.value, color_index))

def tv_layer_color_unlock(color_index: int) -> int:
    """Unlock all layers that use the given color index.

    Args:
        color_index: the layer color index

    Returns:
        the number of unlocked layers
    """
    return int(send_cmd("tv_LayerColor", LayerColorAction.UNLOCK.value, color_index))