Lightly Utilities

0.0.2 · active · verified Thu Apr 16

A utility package for the Lightly computer vision framework, providing helper functions primarily for data reformatting, such as preparing bounding box annotations for web visualization. It is currently at version 0.0.2 and has an irregular release cadence, often tied to releases of the main `lightly` library.

Common errors

```
ModuleNotFoundError: No module named 'lightly_utils'
```
cause The `lightly-utils` package has not been installed in your Python environment.

fix Run `pip install lightly-utils`.
```
AttributeError: module 'lightly' has no attribute 'utils'
```
cause You are attempting to import `lightly_utils` functionality from the `lightly` package. They are distinct packages.

fix Install `lightly-utils` if not already, then import directly: `from lightly_utils import reformat_for_web`.
```
FileNotFoundError: [Errno 2] No such file or directory: './output_web_visuals/dummy_image.json'
```
cause The specified `output_dir` for `reformat_for_web` does not exist.

fix Create the output directory before calling the function: `import os; os.makedirs(output_dir, exist_ok=True)`.
```
KeyError: 'boxes'
```
cause The input `annotations` list of dictionaries does not contain the expected 'boxes' key (or 'labels' if that's missing).

fix Ensure each annotation dictionary has the required keys and structure, e.g., `annotations=[{'boxes': [[0.1, 0.2, 0.3, 0.4]], 'labels': [0]}]`.

Warnings

gotcha Despite living in the same GitHub monorepo, `lightly-utils` is a separate PyPI package from the main `lightly` library. Trying to import utilities directly from `lightly.utils` will result in an `AttributeError` or `ModuleNotFoundError`.
Fix: Ensure you have `lightly-utils` installed via `pip install lightly-utils` and import directly: `from lightly_utils import ...`.
gotcha The `reformat_for_web` function creates files within the specified `output_dir`. If the directory does not exist or the Python process lacks write permissions, a `FileNotFoundError` or `PermissionError` will occur.
Fix: Always ensure the `output_dir` exists before calling `reformat_for_web` using `os.makedirs(output_dir, exist_ok=True)` and verify write permissions for the process.
gotcha The `annotations` parameter for `reformat_for_web` expects a very specific list of dictionaries format, with keys like 'boxes' and 'labels'. Providing an incorrectly structured input will lead to `KeyError` or other runtime errors.
Fix: Refer to the function's docstring or source code for the exact expected format. A typical entry looks like `{'boxes': [[x_norm, y_norm, w_norm, h_norm]], 'labels': [0]}`.

Install

pip install lightly-utils Install latest version

Imports

reformat_for_web
wrong:
```
from lightly.utils import reformat_for_web
```
correct:
```
from lightly_utils import reformat_for_web
```
lightly-utils is a separate PyPI package from 'lightly', despite living in the same monorepo. You must import directly from 'lightly_utils'.

Quickstart

This quickstart demonstrates how to use the `reformat_for_web` function to convert a list of annotations and an image path into a format suitable for web visualization, saving the output to a specified directory. It creates a dummy image and annotations for a runnable example.

import os
import numpy as np
from PIL import Image
from lightly_utils import reformat_for_web

# 1. Create a dummy image file for demonstration
image_filename = "dummy_image.jpg"
Image.fromarray(np.zeros((100, 100, 3), dtype=np.uint8)).save(image_filename)

# 2. Define dummy annotations in the expected format
# Each dictionary represents annotations for one image.
# 'boxes': list of [x_norm, y_norm, width_norm, height_norm]
# 'labels': list of integer class IDs
annotations = [
    {'boxes': [[0.1, 0.2, 0.3, 0.4], [0.5, 0.6, 0.1, 0.1]], 'labels': [0, 1]},
    # In a real scenario, you'd have more entries for more images
]

# 3. Define an output directory
output_dir = "output_web_visuals"
os.makedirs(output_dir, exist_ok=True)

# 4. Call the utility function to reformat data for web visualization
print(f"Reformatting annotations for image: {image_filename}")
reformat_for_web(
    annotations=annotations, # This assumes one image's annotations for simplicity
    image_path=image_filename,
    output_dir=output_dir,
)

print(f"Web-ready data (e.g., image.json) has been written to: {os.path.abspath(output_dir)}")

# Optional: Clean up created files/directories
# os.remove(image_filename)
# import shutil
# shutil.rmtree(output_dir)

view raw JSON →