VSceneExporter

Unified exporter for VScene supporting static and animated exports.

Handles: - Static exports: SVG, PNG, PDF at specific time points - Animation exports: Frame sequences and video files

Constructor

VSceneExporter(
    scene,
    output_dir: Optional[str] = '.',
    converter: ConverterType = <ConverterType.PLAYWRIGHT: 'playwright'>,
    timestamp_files: bool = False
) -> None

Initialize exporter

Parameters

scene: The VScene to export
output_dir: Directory to save exported files
converter: ConverterType enum for PNG/PDF conversion
timestamp_files: Whether to prefix filenames with timestamps

Methods

export

export(
    filename: str,
    frame_time: float = 0.0,
    formats: Optional[list[str]] = None,
    png_width_px: Optional[int] = None,
    png_height_px: Optional[int] = None,
    png_thumbnail_width_px: Optional[int] = None,
    png_thumbnail_height_px: Optional[int] = None,
    pdf_inch_width: Optional[float] = None,
    pdf_inch_height: Optional[float] = None
) -> ExportResult

Export scene at specific time point to various formats.

Parameters

filename: Output filename (extension determines default format)
frame_time: Time point to render (0.0 to 1.0)
formats: List of formats to export (e.g. ["png", "pdf", "svg"])
png_width_px: Width in pixels for PNG export
png_height_px: Height in pixels for PNG export
png_thumbnail_width_px: Width for PNG thumbnail
png_thumbnail_height_px: Height for PNG thumbnail
pdf_inch_width: Width in inches for PDF export
pdf_inch_height: Height in inches for PDF export

Returns

ExportResult with paths to exported files

to_frames

to_frames(
    output_dir: str,
    filename_pattern: str = 'frame_{:04d}',
    total_frames: int = 60,
    format: str = 'svg',
    easing: Optional[Callable[[float], float]] = None,
    png_width_px: Optional[int] = None,
    png_height_px: Optional[int] = None,
    cleanup_svg_after_png_conversion: bool = True,
    progress_callback: Optional[Callable[[int, int], None]] = None
)

Export animation as frame sequence.

Parameters

output_dir: Directory to save frames
filename_pattern: Pattern for frame filenames (must include format placeholder like {:04d})
total_frames: Number of frames to generate
format: Format for frames ("svg", "png", or "pdf")
easing: Optional easing function for animation
png_width_px: Width for PNG frames
png_height_px: Height for PNG frames
cleanup_svg_after_png_conversion: If format is PNG, whether to delete intermediate SVG files
progress_callback: Optional callback(frame_num, total_frames) for progress tracking
Yields: Tuple of (frame_num, frame_time) for progress tracking

to_gif

to_gif(
    filename: str,
    total_frames: int = 60,
    framerate: int = 30,
    easing: Optional[Callable[[float], float]] = None,
    png_width_px: Optional[int] = None,
    png_height_px: Optional[int] = None,
    loop: int = 0,
    optimize: bool = True,
    cleanup_intermediate_files: bool = True,
    progress_callback: Optional[Callable[[int, int], None]] = None
) -> str

Export scene as animated GIF file.

Parameters

filename: Output GIF filename (without extension)
total_frames: Number of frames to generate
framerate: Animation framerate (fps)
easing: Optional easing function
png_width_px: Width for frames
png_height_px: Height for frames
loop: Number of loops (0 = infinite)
optimize: Optimize GIF file size
cleanup_intermediate_files: Whether to delete frame images after encoding
progress_callback: Optional callback(frame_num, total_frames) for progress tracking

Returns

Path to the exported GIF file

to_html

to_html(
    filename: str,
    total_frames: int = 60,
    framerate: int = 30,
    interactive: bool = True,
    embeddable: bool = False
) -> str

Export scene as self-contained HTML file.

Parameters

filename: Output HTML filename (without extension)
total_frames: Number of frames to generate
framerate: Playback framerate (fps)
interactive: If True, includes controls (play/pause, slider). If False, creates auto-playing looping animation.
embeddable: If True, exports only the content (no <html>, <head>, <body> tags) for direct embedding into existing webpages. If False, exports a complete standalone HTML document.

Returns

Path to the exported HTML file

to_mp4

to_mp4(
    filename: str,
    total_frames: int = 60,
    framerate: int = 30,
    easing: Optional[Callable[[float], float]] = None,
    png_width_px: Optional[int] = None,
    png_height_px: Optional[int] = None,
    cleanup_intermediate_files: bool = True,
    codec: str = 'libx264',
    num_thumbnails: int = 0,
    progress_callback: Optional[Callable[[int, int], None]] = None
) -> str

Export scene as MP4 video file, with optional thumbnail generation.

Parameters

filename: Output video filename (without extension)
total_frames: Number of frames to generate
framerate: Video framerate (fps)
easing: Optional easing function
png_width_px: Width for video frames
png_height_px: Height for video frames
cleanup_intermediate_files: Whether to delete frame images after encoding
codec: Video codec (default: libx264 for MP4)
num_thumbnails: Number of thumbnails to generate (0 = none, 1 = middle, 2 = start/end, etc.)
progress_callback: Optional callback(frame_num, total_frames) for progress tracking

Returns

Path to the exported video file

to_pdf

to_pdf(
    filename: str,
    frame_time: float = 0.0,
    pdf_inch_width: Optional[float] = None,
    pdf_inch_height: Optional[float] = None
) -> str

Export scene to PDF at specific time point.

Parameters

filename: Output filename
frame_time: Time point to render (0.0 to 1.0)
pdf_inch_width: Width in inches
pdf_inch_height: Height in inches

Returns

Path to exported PDF file

to_png

to_png(
    filename: str,
    frame_time: float = 0.0,
    png_width_px: Optional[int] = None,
    png_height_px: Optional[int] = None
) -> str

Export scene to PNG at specific time point.

Parameters

filename: Output filename
frame_time: Time point to render (0.0 to 1.0)
png_width_px: Width in pixels
png_height_px: Height in pixels

Returns

Path to exported PNG file