Project class¶

def refresh(self) -> None:
    """Refreshes the project data.

    Raises:
        ValueError: if project has been closed
    """
    if self._is_closed:
        msg = "Project already closed, load the project again to get data"
        raise ValueError(msg)
    if not self.refresh_on_call and self._data:
        return

    self._data = george.tv_project_info(self._id)

def make_current(self) -> None:
    """Make the project the current one."""
    if self.is_current:
        return
    george.tv_project_select(self.id)

@refreshed_property
def path(self) -> Path:
    """The project path on disk."""
    return self._data.path

@set_as_current
def resize(
    self,
    width: int,
    height: int,
    overwrite: bool = False,
    resize_opt: george.ResizeOption | None = None,
) -> Project:
    """Resize the current project and returns a new one.

    Args:
        width: the new width
        height: the new height
        overwrite: overwrite the original project, default is to create a new project
        resize_opt: how to resize the project

    Returns:
        the newly resized project
    """
    if (width, height) == (self.width, self.height):
        return self

    origin_position = self.position
    origin_path = self.path

    if resize_opt:
        george.tv_resize_page(width, height, resize_opt)
    else:
        george.tv_resize_project(width, height)

    # The resized project is at the same position and replaced the original one
    resized_id = george.tv_project_enum_id(origin_position)
    resized_project = Project(resized_id)

    if overwrite:
        resized_project.save(origin_path)

    return resized_project

@set_as_current
def set_fps(
    self,
    fps: float,
    time_stretch: bool = False,
    preview: bool = False,
) -> None:
    """Set the project's framerate."""
    george.tv_frame_rate_set(fps, time_stretch, preview)

@refreshed_property
@set_as_current
def pixel_aspect_ratio(self) -> float:
    """The project's pixel aspect ratio."""
    return self._data.pixel_aspect_ratio

@set_as_current
def clear_background(self) -> None:
    """Clear the background color and set it to None."""
    self.background_mode = george.BackgroundMode.NONE
    self.background_colors = (
        george.RGBColor(255, 255, 255),
        george.RGBColor(0, 0, 0),
    )

@classmethod
def get_project(
    cls,
    by_id: str | None = None,
    by_name: str | None = None,
    by_regex: re.Pattern[str] | None = None,
    by_path: str | Path | None = None,
) -> Project | None:
    """Find a project by id or by name or by path.

    Args:
        by_id: search by id. Defaults to None.
        by_name: search by name, search is case-insensitive. Defaults to None.
        by_regex: search by name using a compiled regex, case-sensitivity is left to the regex. Defaults to None.
        by_path: search by path. Defaults to None.

    Raises:
        ValueError: if none of the search arguments where provided

    Returns:
        Project | None: the searched element or None if search was unsuccessful
    """
    return utils.get_tvp_element(
        Project.open_projects(), by_id=by_id, by_name=by_name, by_regex=by_regex, by_path=by_path
    )

@staticmethod
def current_scene_ids() -> Iterator[int]:
    """Yields the current project's scene ids."""
    return utils.position_generator(lambda pos: george.tv_scene_enum_id(pos))

def get_scene(self, scene_id: int) -> Scene | None:
    """Find a scene in the project by id.

    Args:
        scene_id: scene id

    Returns:
        Scene | None: the searched element or None if search was unsuccessful
    """
    for scene in self.scenes:
        if scene.id != scene_id:
            continue
        return scene

    return None

@set_as_current
def add_scene(self) -> Scene:
    """Add a new scene in the project."""
    from pytvpaint.scene import Scene

    return Scene.new(project=self)

def get_clip(
    self,
    by_id: int | None = None,
    by_name: str | None = None,
    by_regex: re.Pattern[str] | None = None,
    scene_id: int | None = None,
) -> Clip | None:
    """Find a clip by id or name, filter search by scene_id if needed.

    Args:
        by_id: search by id. Defaults to None.
        by_name: search by name, search is case-insensitive. Defaults to None.
        by_regex: search by name using a compiled regex, case-sensitivity is left to the regex. Defaults to None.
        scene_id: parent scene id. Defaults to None.

    Raises:
        ValueError: if none of the search arguments where provided

    Returns:
        Clip | None: the searched element or None if search was unsuccessful
    """
    clips = self.clips
    if scene_id:
        selected_scene = self.get_scene(scene_id=scene_id)
        clips = selected_scene.clips if selected_scene else clips

    return utils.get_tvp_element(clips, by_id=by_id, by_name=by_name, by_regex=by_regex)

def add_clip(self, clip_name: str, scene: Scene | None = None) -> Clip:
    """Add a new clip in the given scene or the current one if no scene provided."""
    scene = scene or self.current_scene
    return scene.add_clip(clip_name)

def add_sound(self, sound_path: Path | str) -> ProjectSound:
    """Add a new sound clip to the project."""
    return ProjectSound.new(sound_path, parent=self)

@set_as_current
def guidelines(self, by_type: george.GuidelineType | None = None) -> Iterator[guideline.Guideline[Any, Any]]:
    """Iterator for the `Guideline` objects of the project."""
    guideline_classes = {
        c.TYPE: c  # type: ignore[attr-defined]
        for c in [
            guideline.GuidelineImage,
            guideline.GuidelineLine,
            guideline.GuidelineSegment,
            guideline.GuidelineCircle,
            guideline.GuidelineEllipse,
            guideline.GuidelineGrid,
            guideline.GuidelineMarks,
            guideline.GuidelineSafeArea,
            guideline.GuidelineFieldChart,
            guideline.GuidelineAnimatorField,
            guideline.GuidelineVanishPoint1,
            guideline.GuidelineVanishPoint2,
            guideline.GuidelineVanishPoint3,
        ]
    }
    for g_type in george.GuidelineType:
        if by_type and by_type != g_type:
            continue
        if not guideline_classes.get(g_type):
            continue

        guideline_class = guideline_classes[g_type]

        positions = utils.position_generator(lambda pos: george.tv_guideline_enum(pos, g_type))
        for position in positions:
            yield guideline_class(position, project=self)

def add_guideline_image(
    self,
    img_path: Path | str | None = None,
    x: float | None = None,
    y: float | None = None,
    rotation: float | None = None,
    scale: float | None = None,
    flip: george.FlipDirection | None = None,
    alpha_mode: george.GuidelineAlphaMode | None = None,
) -> guideline.GuidelineImage:
    """Add a new image guideline to the project."""
    return guideline.GuidelineImage.new(self, img_path, x, y, rotation, scale, flip, alpha_mode)

def add_guideline_line(
    self,
    x: float | None = None,
    y: float | None = None,
    angle: float | None = None,
) -> guideline.GuidelineLine:
    """Add a new line guideline to the project."""
    return guideline.GuidelineLine.new(self, x, y, angle)

def add_guideline_segment(
    self,
    x1: float | None = None,
    y1: float | None = None,
    x2: float | None = None,
    y2: float | None = None,
) -> guideline.GuidelineSegment:
    """Add a new segment guideline to the project."""
    return guideline.GuidelineSegment.new(self, x1, y1, x2, y2)

def add_guideline_circle(
    self,
    x: float | None = None,
    y: float | None = None,
    radius: float | None = None,
) -> guideline.GuidelineCircle:
    """Add a new segment guideline to the project."""
    return guideline.GuidelineCircle.new(self, x, y, radius)

def add_guideline_ellipse(
    self,
    x: float | None = None,
    y: float | None = None,
    radius_a: float | None = None,
    radius_b: float | None = None,
) -> guideline.GuidelineEllipse:
    """Add a new ellipse guideline to the project."""
    return guideline.GuidelineEllipse.new(self, x, y, radius_a, radius_b)

def add_guideline_grid(
    self,
    x: float | None = None,
    y: float | None = None,
    width: float | None = None,
    height: float | None = None,
) -> guideline.GuidelineGrid:
    """Add a new grid guideline to the project."""
    return guideline.GuidelineGrid.new(self, x, y, width, height)

def add_guideline_marks(
    self,
    count_x: int | None = None,
    count_y: int | None = None,
) -> guideline.GuidelineMarks:
    """Add a new marks guideline to the project."""
    return guideline.GuidelineMarks.new(self, count_x, count_y)

def add_guideline_field_chart(
    self,
) -> guideline.GuidelineFieldChart:
    """Add a new field chart guideline to the project."""
    return guideline.GuidelineFieldChart.new(self)

def add_guideline_animator_field(
    self,
) -> guideline.GuidelineAnimatorField:
    """Add a new animator field guideline to the project."""
    return guideline.GuidelineAnimatorField.new(self)

def add_guideline_safe_area(
    self,
    sf_out: int | None = None,
    sf_in: int | None = None,
) -> guideline.GuidelineSafeArea:
    """Add a new safe area guideline to the project."""
    return guideline.GuidelineSafeArea.new(self, sf_out, sf_in)

def add_guideline_vanishing_point1(
    self,
    x: float | None = None,
    y: float | None = None,
    grid: bool | None = None,
) -> guideline.GuidelineVanishPoint1:
    """Add a new vanishing point1 guideline to the project."""
    return guideline.GuidelineVanishPoint1.new(self, x, y, grid)

def add_guideline_vanishing_point2(
    self,
    x1: float | None = None,
    y1: float | None = None,
    x2: float | None = None,
    y2: float | None = None,
) -> guideline.GuidelineVanishPoint2:
    """Add a new vanishing point2 guideline to the project."""
    return guideline.GuidelineVanishPoint2.new(self, x1, y1, x2, y2)

def add_guideline_vanishing_point3(
    self,
    x1: float | None = None,
    y1: float | None = None,
    x2: float | None = None,
    y2: float | None = None,
    x3: float | None = None,
    y3: float | None = None,
) -> guideline.GuidelineVanishPoint3:
    """Add a new vanishing point2 guideline to the project."""
    return guideline.GuidelineVanishPoint3.new(self, x1, y1, x2, y2, x3, y3)

@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 project 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 or the mark in or the project's start frame if None. Defaults to None.
        end: the end frame to render or the mark out or the project's end frame 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 george.BackgroundMode.NONE.
        format_opts: custom format options. Defaults to None.

    Raises:
        ValueError: if requested range (start-end) not in project range/bounds
        ValueError: if output is a movie, and it's duration is equal to 1 frame
        FileNotFoundError: if the render failed and no files were found on disk or missing frames

    Note:
        This functions uses the project's timeline as a basis for the range (start-end). This timeline includes all
        the project's clips and is different from a clip range. 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
    """
    default_start = self.mark_in or self.start_frame
    default_end = self.mark_out or self.end_frame

    return self._render(
        output_path=output_path,
        default_start=default_start,
        default_end=default_end,
        start=start,
        end=end,
        frame_set=frame_set,
        use_camera=use_camera,
        layer_selection=None,
        alpha_mode=alpha_mode,
        background_mode=background_mode,
        format_opts=format_opts,
    )

@set_as_current
def render_clips(
    self,
    clips: list[Clip],
    output_path: Path | str | FileSequence,
    use_camera: bool = False,
    alpha_mode: george.AlphaSaveMode = george.AlphaSaveMode.PREMULTIPLY,
    background_mode: george.BackgroundMode | None = None,
    format_opts: list[str] | None = None,
) -> None:
    """Render sequential clips as a single output."""
    clips = sorted(clips, key=lambda c: c.position)
    start = clips[0].timeline_start
    end = clips[-1].timeline_end

    self.render(
        output_path=output_path,
        frame_set=FrameSet(f"{start}-{end}"),
        use_camera=use_camera,
        alpha_mode=alpha_mode,
        background_mode=background_mode,
        format_opts=format_opts,
    )

@staticmethod
def current_project_id() -> str:
    """Returns the current project id."""
    return george.tv_project_current_id()

@staticmethod
def current_project() -> Project:
    """Returns the current project."""
    return Project(project_id=Project.current_project_id())

@staticmethod
def open_projects_ids() -> Iterator[str]:
    """Yields the ids of the currently open projects."""
    return utils.position_generator(lambda pos: george.tv_project_enum_id(pos))

@classmethod
def open_projects(cls) -> Iterator[Project]:
    """Returns an iterator over the currently open projects."""
    for project_id in Project.open_projects_ids():
        yield Project(project_id)

@classmethod
def new(
    cls,
    project_path: Path | str,
    width: int = 1920,
    height: int = 1080,
    pixel_aspect_ratio: float = 1.0,
    frame_rate: float = 24.0,
    field_order: george.FieldOrder = george.FieldOrder.NONE,
    start_frame: int = 1,
) -> Project:
    """Create a new project."""
    george.tv_project_new(
        Path(project_path).resolve().as_posix(),
        width,
        height,
        pixel_aspect_ratio,
        frame_rate,
        field_order,
        start_frame,
    )
    return cls.current_project()

@set_as_current
def new_from_camera(self, export_path: Path | str | None = None) -> Project:
    """Create a new cropped project from the camera view."""
    cam_project_id = george.tv_project_render_camera(self.id)
    cam_project = Project(cam_project_id)

    if export_path:
        export_path = Path(export_path)
        export_path.mkdir(exist_ok=True, parents=True)
        cam_project.save(export_path)

    return cam_project

@set_as_current
def duplicate(self) -> Project:
    """Duplicate the project and return the new one."""
    george.tv_project_duplicate()
    duplicated = Project.current_project()
    self.make_current()
    return duplicated

def close(self) -> None:
    """Closes the project."""
    self._is_closed = True
    george.tv_project_close(self._id)

@classmethod
def close_all(cls, close_tvp: bool = False) -> None:
    """Closes all open projects.

    Args:
        close_tvp: close the TVPaint instance as well
    """
    for project in list(cls.open_projects()):
        project.close()

    if close_tvp:
        george.tv_quit()

@classmethod
def load(cls, project_path: Path | str, silent: bool = True) -> Project:
    """Load an existing .tvpp/.tvp project or .tvpx file."""
    project_path = Path(project_path)

    # Check if project not already open, if so, return it
    for project in cls.open_projects():
        if project.path == project_path:
            return project

    george.tv_load_project(project_path, silent)
    return cls.current_project()

def save(self, save_path: Path | str | None = None) -> None:
    """Saves the project on disk."""
    save_path = Path(save_path or self.path).resolve()
    george.tv_save_project(save_path.as_posix())

@set_as_current
def load_panel(self, panel_path: Path | str) -> None:
    """Load an external TVPaint panel."""
    george.tv_load_project(panel_path, silent=True)

@set_as_current
def load_palette(self, palette_path: Path | str) -> None:
    """Load a palette."""
    george.tv_save_palette(palette_path)

@set_as_current
def save_palette(self, save_path: Path | str | None = None) -> None:
    """Save a palette to the given path."""
    save_path = Path(save_path or self.path)
    george.tv_save_project(save_path)

@set_as_current
def save_video_dependencies(self, on_save: bool = True, now: bool = True) -> None:
    """Saves the video dependencies."""
    george.tv_project_save_video_dependencies(self.id, on_save, now)

@set_as_current
def save_audio_dependencies(self, on_save: bool = True) -> None:
    """Saves audio dependencies."""
    george.tv_project_save_audio_dependencies(self.id, on_save)