maskstudio 0.1.0

Vector-first desktop mask annotation studio for batch image workflows.

maskstudio

MaskStudio is a vector-first desktop mask annotation studio for batch image workflows. It opens a folder or a single image, keeps editable annotations as Shapely geometry in image coordinates, and saves deterministic grayscale PNG masks beside the source images.

Supported operations

• Open a folder or single image (non-interactive path resolution)
• Paint, polygon, rectangle, and hole tools with edge-aware refinement
• Contour edit mode with vertex and edge handles
• Overview plus detail split view with adjustable ROI
• Undo/redo history per document
• Deterministic <stem>_mask.png output (mode L, black mask on white)

Requirements

• Python 3.12 or newer
• Dependencies installed automatically by pip: numpy, opencv-python, Pillow, pydantic, PySide6, shapely
• On Linux, a working X11 or Wayland session is required for the Qt runtime

Install

pip install maskstudio

Checking the version

import maskstudio

print(maskstudio.__version__)

Configuration

MaskStudio does not require credentials or environment variables. Inputs are passed either to the Python API or to the installed CLI launcher.

import maskstudio

result = maskstudio.annotate_masks()
result = maskstudio.annotate_masks("/path/to/folder")
result = maskstudio.annotate_masks("/path/to/image.png")

maskstudio
maskstudio /path/to/folder
maskstudio /path/to/image.png

See docs/configuration.md for the detailed input resolution flow and supported raster formats.

Quickstart

Annotate every image in a folder

import maskstudio

result = maskstudio.annotate_masks("/path/to/folder")
for saved_mask in result:
    print(saved_mask)

Annotate a single image

import maskstudio

result = maskstudio.annotate_masks("/path/to/image.png")
print(f"Saved {len(result)} mask(s)")

Open the graphical folder picker

import maskstudio

result = maskstudio.annotate_masks()
if not result.saved_paths:
    print("Session finished with no saved masks")

Use the installed CLI launcher

maskstudio /path/to/folder

Public API

Module	Symbol	Description
maskstudio	annotate_masks(path=None)	Launch the GUI and return an AnnotationResult.
maskstudio	__version__	Installed package version string.
maskstudio.models	AnnotationRequest	Frozen Pydantic request with optional path.
maskstudio.models	AnnotationResult	Frozen Pydantic result with saved_paths.
maskstudio.exceptions	MaskStudioError	Base class for every typed exception.
maskstudio.exceptions	NoImagesFoundError	Raised when a folder has no supported images.
maskstudio.exceptions	UnsupportedImageError	Raised when a file is not a supported image.

Supported input formats

The discovery layer accepts these raster formats case-insensitively: .png, .jpg, .jpeg, .bmp, .tif, .tiff, .webp. Files whose name already matches *_mask.png are skipped during folder scanning.

Saved output rules

• Output path is always <original_stem>_mask.png in the source directory.
• Saved masks are always PNG, mode L.
• Background pixels are white (255); annotated pixels are black (0).
• Saved files never contain alpha, outlines, or display-only styling.

Error handling

import maskstudio
from maskstudio.exceptions import MaskStudioError, NoImagesFoundError

try:
    result = maskstudio.annotate_masks("/path/to/folder")
except NoImagesFoundError as error:
    print(f"No images in {error.path}")
except MaskStudioError as error:
    print(f"MaskStudio failed: {error}")

See docs/errors.md for the full exception hierarchy.

Additional docs

• docs/configuration.md — Input resolution, picker behavior, and supported formats.
• docs/errors.md — Exception hierarchy and recovery patterns.

Contributing

See CONTRIBUTING.md for the development setup, test commands, and the full build and publish workflow.