{"id":8279,"library":"lightly-utils","title":"Lightly Utilities","description":"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.","status":"active","version":"0.0.2","language":"en","source_language":"en","source_url":"https://github.com/lightly-ai/lightly/tree/main/lightly_utils","tags":["lightly","utilities","computer-vision","data-processing","annotations"],"install":[{"cmd":"pip install lightly-utils","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for image processing operations within `reformat_for_web`.","package":"Pillow"},{"reason":"Required for numerical operations, particularly array handling in `reformat_for_web`.","package":"numpy"},{"reason":"The core Lightly library, which `lightly-utils` complements. Declared in `setup.cfg`.","package":"lightly"}],"imports":[{"note":"lightly-utils is a separate PyPI package from 'lightly', despite living in the same monorepo. You must import directly from 'lightly_utils'.","wrong":"from lightly.utils import reformat_for_web","symbol":"reformat_for_web","correct":"from lightly_utils import reformat_for_web"}],"quickstart":{"code":"import os\nimport numpy as np\nfrom PIL import Image\nfrom lightly_utils import reformat_for_web\n\n# 1. Create a dummy image file for demonstration\nimage_filename = \"dummy_image.jpg\"\nImage.fromarray(np.zeros((100, 100, 3), dtype=np.uint8)).save(image_filename)\n\n# 2. Define dummy annotations in the expected format\n# Each dictionary represents annotations for one image.\n# 'boxes': list of [x_norm, y_norm, width_norm, height_norm]\n# 'labels': list of integer class IDs\nannotations = [\n    {'boxes': [[0.1, 0.2, 0.3, 0.4], [0.5, 0.6, 0.1, 0.1]], 'labels': [0, 1]},\n    # In a real scenario, you'd have more entries for more images\n]\n\n# 3. Define an output directory\noutput_dir = \"output_web_visuals\"\nos.makedirs(output_dir, exist_ok=True)\n\n# 4. Call the utility function to reformat data for web visualization\nprint(f\"Reformatting annotations for image: {image_filename}\")\nreformat_for_web(\n    annotations=annotations, # This assumes one image's annotations for simplicity\n    image_path=image_filename,\n    output_dir=output_dir,\n)\n\nprint(f\"Web-ready data (e.g., image.json) has been written to: {os.path.abspath(output_dir)}\")\n\n# Optional: Clean up created files/directories\n# os.remove(image_filename)\n# import shutil\n# shutil.rmtree(output_dir)\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you have `lightly-utils` installed via `pip install lightly-utils` and import directly: `from lightly_utils import ...`.","message":"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`.","severity":"gotcha","affected_versions":"0.0.1, 0.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.1, 0.0.2"},{"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]}`.","message":"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.","severity":"gotcha","affected_versions":"0.0.1, 0.0.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install lightly-utils`.","cause":"The `lightly-utils` package has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'lightly_utils'"},{"fix":"Install `lightly-utils` if not already, then import directly: `from lightly_utils import reformat_for_web`.","cause":"You are attempting to import `lightly_utils` functionality from the `lightly` package. They are distinct packages.","error":"AttributeError: module 'lightly' has no attribute 'utils'"},{"fix":"Create the output directory before calling the function: `import os; os.makedirs(output_dir, exist_ok=True)`.","cause":"The specified `output_dir` for `reformat_for_web` does not exist.","error":"FileNotFoundError: [Errno 2] No such file or directory: './output_web_visuals/dummy_image.json'"},{"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]}]`.","cause":"The input `annotations` list of dictionaries does not contain the expected 'boxes' key (or 'labels' if that's missing).","error":"KeyError: 'boxes'"}]}