Project class

Project class.

Project(project_id: str)

Bases: pytvpaint.utils.Refreshable, pytvpaint.utils.Renderable

A TVPaint project is the highest object that contains everything in the data hierarchy.

It looks like this: Project -> Scene -> Clip -> Layer -> LayerInstance

Source code in pytvpaint/project.py

def __init__(self, project_id: str) -> None:
    super().__init__()
    self._id = project_id
    self._is_closed = False
    self._data = george.tv_project_info(self._id)

id: str property

The project id.

Note

the id is persistent on project load/close.

position: int property

The project's position in the project tabs.

Raises:

Type	Description
ValueError	if project cannot be found in open projects

Note

the indices go from right to left in the UI

is_closed: bool property

Returns True if the project is closed.

exists: bool property

Checks if the project exists on disk.

is_current: bool property

Returns True if the project is the current selected one in the UI.

name: str property

The name of the project which is the filename without the extension.

width: int property

The width of the canvas.

height: int property

The height of the canvas.

fps: float property

The project's framerate.

playback_fps: float property

The project's playback framerate.

field_order: george.FieldOrder property

The field order.

start_frame: int property writable

The project's start frame.

end_frame: int property

The project's end frame, meaning the last frame of the last clip in the project's timeline.

current_frame: int property writable

Get the current frame relative to the timeline.

background_mode: george.BackgroundMode property writable

Get/Set the background mode.

background_colors: tuple[george.RGBColor, george.RGBColor] | george.RGBColor | None property writable

Get/Set the background color(s).

Returns:

Type	Description
tuple[pytvpaint.george.RGBColor, pytvpaint.george.RGBColor] | pytvpaint.george.RGBColor | None	a tuple of two colors if checker, a single color if solid or None if empty

header_info: str property writable

The project's header info.

author: str property writable

The project's author info.

notes: str property writable

The project's notes text.

current_scene: Scene property

Get the current scene of the project.

Raises:

Type	Description
ValueError	if scene cannot be found in project

scenes: Iterator[Scene] property

Yields the project's scenes.

current_clip: Clip property

Returns the project's current clip.

clips: Iterator[Clip] property

Iterates over all the clips in the project's scenes.

clip_names: Iterator[str] property

Optimized way to get the clip names. Useful for get_unique_name.

sounds: Iterator[ProjectSound] property

Iterator over the project sounds.

mark_in: int | None property writable

Get the project mark in or None if no mark in set.

mark_out: int | None property writable

Get the project mark out or None if no mark out set.

refresh() -> None

Refreshed the project data.

Raises:

Type	Description
ValueError	if project has been closed

Source code in pytvpaint/project.py

def refresh(self) -> None:
    """Refreshed 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)

make_current() -> None

Make the project the current one.

Source code in pytvpaint/project.py

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

path() -> Path

The project path on disk.

Source code in pytvpaint/project.py

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

resize(width: int, height: int, overwrite: bool = False, resize_opt: george.ResizeOption | None = None) -> Project

Resize the current project and returns a new one.

Parameters:

Name	Type	Description	Default
width	int	the new width	required
height	int	the new height	required
overwrite	bool	overwrite the original project, default is to create a new project	False
resize_opt	pytvpaint.george.ResizeOption | None	how to resize the project	None

Returns:

Type	Description
pytvpaint.project.Project	the newly resized project

Source code in pytvpaint/project.py

@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_fps(fps: float, time_stretch: bool = False, preview: bool = False) -> None

Set the project's framerate.

Source code in pytvpaint/project.py

@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)

pixel_aspect_ratio() -> float

The project's pixel aspect ratio.

Source code in pytvpaint/project.py

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

clear_background() -> None

Clear the background color and set it to None.

Source code in pytvpaint/project.py

@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),
    )

get_project(by_id: str | None = None, by_name: str | None = None) -> Project | None classmethod

Find a project by id or by name.

Source code in pytvpaint/project.py

@classmethod
def get_project(
    cls,
    by_id: str | None = None,
    by_name: str | None = None,
) -> Project | None:
    """Find a project by id or by name."""
    for project in Project.open_projects():
        if (by_id and project.id == by_id) or (by_name and project.name == by_name):
            return project

    return None

current_scene_ids() -> Iterator[int] staticmethod

Yields the current project's scene ids.

Source code in pytvpaint/project.py

@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))

get_scene(by_id: int | None = None, by_name: str | None = None) -> Scene | None

Find a scene in the project by id or name.

Source code in pytvpaint/project.py

def get_scene(
    self,
    by_id: int | None = None,
    by_name: str | None = None,
) -> Scene | None:
    """Find a scene in the project by id or name."""
    for scene in self.scenes:
        if (by_id and scene.id == by_id) or (by_name and scene.name == by_name):
            return scene

    return None

add_scene() -> Scene

Add a new scene in the project.

Source code in pytvpaint/project.py

@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)

get_clip(by_id: int | None = None, by_name: str | None = None, scene_id: int | None = None) -> Clip | None

Find a clip by id, name or scene_id.

Source code in pytvpaint/project.py

def get_clip(
    self,
    by_id: int | None = None,
    by_name: str | None = None,
    scene_id: int | None = None,
) -> Clip | None:
    """Find a clip by id, name or scene_id."""
    clips = self.clips
    if scene_id:
        selected_scene = self.get_scene(by_id=scene_id)
        clips = selected_scene.clips if selected_scene else clips

    for clip in clips:
        if (by_id and clip.id == by_id) or (by_name and clip.name == by_name):
            return clip

    return None

add_clip(clip_name: str, scene: Scene | None = None) -> Clip

Add a new clip in the given scene or the current one if no scene provided.

Source code in pytvpaint/project.py

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)

add_sound(sound_path: Path | str) -> ProjectSound

Add a new sound clip to the project.

Source code in pytvpaint/project.py

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

render(output_path: Path | str | FileSequence, start: int | None = None, end: int | 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) -> None

Render the project to a single frame or frame sequence or movie.

Parameters:

Name	Type	Description	Default
output_path	pathlib.Path | str | fileseq.filesequence.FileSequence	a single file or file sequence pattern	required
start	int | None	the start frame to render or the mark in or the project's start frame if None. Defaults to None.	None
end	int | None	the end frame to render or the mark out or the project's end frame if None. Defaults to None.	None
use_camera	bool	use the camera for rendering, otherwise render the whole canvas. Defaults to False.	False
alpha_mode	pytvpaint.george.AlphaSaveMode	the alpha mode for rendering. Defaults to george.AlphaSaveMode.PREMULTIPLY.	pytvpaint.george.AlphaSaveMode.PREMULTIPLY
background_mode	pytvpaint.george.BackgroundMode | None	the background mode for rendering. Defaults to george.BackgroundMode.NONE.	None
format_opts	list[str] | None	custom format options. Defaults to None.	None

Raises:

Type	Description
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.

Source code in pytvpaint/project.py

@set_as_current
def render(
    self,
    output_path: Path | str | FileSequence,
    start: int | None = None,
    end: int | 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,
) -> None:
    """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.
        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.
    """
    default_start = self.mark_in or self.start_frame
    default_end = self.mark_out or self.end_frame

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

render_clips(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.

Source code in pytvpaint/project.py

@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,
        start,
        end,
        use_camera,
        alpha_mode,
        background_mode,
        format_opts,
    )

current_project_id() -> str staticmethod

Returns the current project id.

Source code in pytvpaint/project.py

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

current_project() -> Project staticmethod

Returns the current project.

Source code in pytvpaint/project.py

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

open_projects_ids() -> Iterator[str] staticmethod

Yields the ids of the currently open projects.

Source code in pytvpaint/project.py

@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))

open_projects() -> Iterator[Project] classmethod

Iterator over the currently open projects.

Source code in pytvpaint/project.py

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

new(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 classmethod

Create a new project.

Source code in pytvpaint/project.py

@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()

new_from_camera(export_path: Path | str | None = None) -> Project

Create a new cropped project from the camera view.

Source code in pytvpaint/project.py

@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

duplicate() -> Project

Duplicate the project and return the new one.

Source code in pytvpaint/project.py

@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

close() -> None

Closes the project.

Source code in pytvpaint/project.py

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

close_all(close_tvp: bool = False) -> None classmethod

Closes all open projects.

Parameters:

Name	Type	Description	Default
close_tvp	bool	close the TVPaint instance as well	False

Source code in pytvpaint/project.py

@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()

load(project_path: Path | str, silent: bool = True) -> Project classmethod

Load an existing .tvpp/.tvp project or .tvpx file.

Source code in pytvpaint/project.py

@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()

save(save_path: Path | str | None = None) -> None

Saves the project on disk.

Source code in pytvpaint/project.py

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())

load_panel(panel_path: Path | str) -> None

Load an external TVPaint panel.

Source code in pytvpaint/project.py

@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)

load_palette(palette_path: Path | str) -> None

Load a palette.

Source code in pytvpaint/project.py

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

save_palette(save_path: Path | str | None = None) -> None

Save a palette to the given path.

Source code in pytvpaint/project.py

@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)

save_video_dependencies(on_save: bool = True, now: bool = True) -> None

Saves the video dependencies.

Source code in pytvpaint/project.py

@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)

save_audio_dependencies(on_save: bool = True) -> None

Saves audio dependencies.

Source code in pytvpaint/project.py

@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)