Sinapsis Image Transforms

Templates for applying image transformations using Albumentations.

🐍 Installation • 🚀 Features • 🌐 Webapp • 📙 Documentation • 🔍 License

The sinapsis-image-transforms module provides templates for applying various image transformations with Albumentations.

🐍 Installation

Install using your package manager of choice. We encourage the use of uv

Example with uv:

  uv pip install sinapsis-image-transforms --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-image-transforms --extra-index-url https://pypi.sinapsis.tech

🚀 Features

Templates Supported

The Sinapsis Image Transforms module provides a collection of templates for applying image transformations using Albumentations. These templates allow users to apply a wide range of augmentations, from simple operations like flipping and resizing to more advanced transformations such as elastic distortions and geometric warping.

🌍 General Attributes

Note

All templates share the following attributes:

• apply_to_annotations (bool, optional): Determines whether transformations should also be applied to annotations like bounding boxes, keypoints, and masks. Defaults to False.
• bbox_params (dict[str, Any], optional): Configuration for transforming bounding boxes, following Albumentations' BboxParams format. Defaults to None.
• keypoints_params (dict[str, Any], optional): Defines keypoint transformation settings using Albumentations' KeypointParams. Defaults to None.
• additional_targets (dict[str, Any], optional): Specifies extra annotation types (e.g., segmentation masks) to be transformed alongside the image. Defaults to {"mask": "mask"}.

Additional transformation-specific attributes can be dynamically assigned through the class initialization dictionary (*_init attributes). These attributes correspond directly to the arguments used in Albumentations.

Tip

Use CLI command sinapsis info --all-template-names to show a list with all the available Template names installed with Sinapsis Image Transforms.

Tip

Use CLI command sinapsis info --example-template-config TEMPLATE_NAME to produce an example Agent config for the Template specified in TEMPLATE_NAME.

For example, for RotateWrapper use sinapsis info --example-template-config RotateWrapper to produce the following example config:

agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
- template_name: RotateWrapper
  class_name: RotateWrapper
  template_input: InputTemplate
  attributes:
    apply_to_annotations: false
    bbox_params: null
    keypoints_params: null
    additional_targets:
      mask: mask
    rotate_init:
      limit: [-45, 45]
      interpolation: 1
      border_mode: 4
      value: [0, 0, 0]
      mask_value: null
      rotate_method: "largest_box"
      crop_border: false
      fill_value: 0
      mask_fill_value: 0
      deterministic: true
      p: 1.0

📚 Example Usage

The following example demonstrates how to use Sinapsis Image Transforms to apply multiple image augmentations. This setup loads a dataset of images, applies horizontal flipping and elastic transformation, and saves the results. Below is the full YAML configuration, followed by a breakdown of each component.

Config

agent:
  name: transforms_agent

templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}

- template_name: FolderImageDatasetCV2
  class_name: FolderImageDatasetCV2
  template_input: InputTemplate
  attributes:
    data_dir: my_dataset

- template_name: HorizontalFlip
  class_name: HorizontalFlipWrapper
  template_input: FolderImageDatasetCV2
  attributes:
    horizontalflip_init:
      p: 1.0

- template_name: ElasticTransform
  class_name: ElasticTransformWrapper
  template_input: HorizontalFlip
  attributes:
    elastictransform_init:
      mask_value: 150
      p: 1.0
      alpha: 100
      sigma: 50

- template_name: ImageSaver
  class_name: ImageSaver
  template_input: ElasticTransform
  attributes:
    save_dir: results
    extension: jpg

This configuration defines an **agent** and a sequence of **templates** to apply image transformations.

[!IMPORTANT] Attributes specified under the *_init keys (e.g., elastictransform_init, horizontalflip_init) correspond directly to the Albumentations transformation parameters. Ensure that values are assigned correctly according to the official Albumentations documentation, as they affect the behavior and performance of each transformation.

The FolderImageDataserCV2 and ImageSaver correspond to sinapsis-data-readers and sinapsis-data-writers. If you want to use the example, please make sure you install the packages.

To run the config, use the CLI:

sinapsis run name_of_config.yml

🌐 Webapp

The webapp provides an interactive interface to visualize and experiment with image transformations in real time.

Important

To run the app you first need to clone this repository:

git clone git@github.com:Sinapsis-ai/sinapsis-image-transforms.git
cd sinapsis-image-transforms

Note

If you'd like to enable external app sharing in Gradio, export GRADIO_SHARE_APP=True

🐳 Docker

IMPORTANT This docker image depends on the sinapsis-nvidia:base image. Please refer to the official sinapsis instructions to Build with Docker.

1. Build the sinapsis-image-transforms image:

docker compose -f docker/compose.yaml build

2. Start the app container:

docker compose -f docker/compose_apps.yaml up sinapsis-image-transforms-gradio -d

3. Check the status:

docker logs -f sinapsis-image-transforms-inference-gradio

3. The logs will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of logs

Running on local URL:  http://127.0.0.1:7860

4. To stop the app:

docker compose -f docker/compose_apps.yaml down

💻 UV

To run the webapp using the uv package manager, please:

1. Create the virtual environment and sync the dependencies:

uv sync --frozen

2. Install the wheel:

uv pip install sinapsis-image-transforms[webapp-gradio] --extra-index-url https://pypi.sinapsis.tech

3. Activate the environment:

source .venv/bin/activate

4. Run the webapp:

python webapps/gradio_image_transform_visualizer.py

5. The terminal will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of the terminal

Running on local URL:  http://127.0.0.1:7860

📙 Documentation

Documentation for this and other sinapsis packages is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.