{"id":9181,"library":"pims","title":"Python Image Sequence (PIMS)","description":"PIMS (Python Image Sequence) provides a lazy-loading, NumPy-like interface for accessing sequential image and video data from various file formats. It handles diverse inputs, including image directories, TIFF stacks, and common video formats, offering a consistent API for slicing and iteration. The library is actively maintained, with a recent major release (v0.7) in June 2024.","status":"active","version":"0.7","language":"en","source_language":"en","source_url":"https://github.com/soft-matter/pims","tags":["image processing","video processing","scientific computing","lazy loading","data sequences","bio-formats"],"install":[{"cmd":"pip install pims","lang":"bash","label":"Basic Installation"},{"cmd":"pip install pims[all]","lang":"bash","label":"With common optional dependencies (ffmpeg, imageio, Pillow, PyAV, scikit-image)"},{"cmd":"pip install pims imageio-ffmpeg","lang":"bash","label":"For video support (recommended alternative to pims[all])"}],"dependencies":[{"reason":"Core dependency for array-like data handling.","package":"numpy","optional":false},{"reason":"Used for lazy-loading pipelines.","package":"slicerator","optional":false},{"reason":"Required for basic image reading.","package":"scikit-image","optional":true},{"reason":"Required for basic image reading and display.","package":"matplotlib","optional":true},{"reason":"For improved TIFF support and other image formats.","package":"Pillow","optional":true},{"reason":"Alternative TIFF support.","package":"tifffile","optional":true},{"reason":"Multi-purpose reader/writer, often used with `imageio-ffmpeg` for video.","package":"imageio","optional":true},{"reason":"Provides FFmpeg binaries and wrapper for video formats (AVI, MOV, MP4).","package":"imageio-ffmpeg","optional":true},{"reason":"Alternative for video formats (AVI, MOV, H.264) using FFmpeg.","package":"pyav","optional":true},{"reason":"Interface with Bio-formats for microscopy file support.","package":"jpype1","optional":true},{"reason":"Improved Nikon .nd2 support.","package":"pims_nd2","optional":true},{"reason":"Python module for video editing, can be used by PIMS for video files.","package":"moviepy","optional":true}],"imports":[{"symbol":"open","correct":"import pims\nimages = pims.open('path/to/files/*.tif')"},{"symbol":"ImageSequence","correct":"from pims import ImageSequence\nimages = ImageSequence('path/to/images/*.png')"},{"symbol":"as_grey","correct":"from pims import as_grey, open\ncolored_images = pims.open('path/to/color_images/*.tif')\ngreyscale_images = as_grey(colored_images)"}],"quickstart":{"code":"import pims\nimport numpy as np\nimport os\n\n# Create dummy image files for demonstration\nif not os.path.exists('test_images'):\n    os.makedirs('test_images')\nfor i in range(5):\n    # Using a minimal image writing approach or mocking if actual image lib is heavy\n    # For real use, ensure Pillow or scikit-image is installed.\n    try:\n        from PIL import Image\n        img = Image.new('L', (10, 10), color = i * 50)\n        img.save(f'test_images/frame_{i:02d}.png')\n    except ImportError:\n        print(\"Pillow not found, cannot create dummy images. Skipping image creation.\")\n        break\n\n# Open a sequence of images\ntry:\n    frames = pims.open('test_images/frame_*.png')\n    print(f\"Opened sequence with {len(frames)} frames.\")\n    \n    # Access a single frame (lazy loading)\n    first_frame = frames[0]\n    print(f\"Shape of the first frame: {first_frame.shape}\")\n    print(f\"Pixel value at (0,0) in first frame: {first_frame[0, 0]}\")\n    \n    # Iterate through frames\n    sum_pixels = 0\n    for frame in frames:\n        sum_pixels += np.sum(frame)\n    print(f\"Total sum of all pixel values: {sum_pixels}\")\n\n    # Slicing returns another lazy-loading object\n    sub_sequence = frames[1:4]\n    print(f\"Sub-sequence has {len(sub_sequence)} frames.\")\n\n    # Example with a specific reader (if 'test_tiff.tif' existed)\n    # from pims import TiffStack\n    # tiff_stack = TiffStack('test_tiff.tif')\n    # print(f\"Tiff stack has {len(tiff_stack)} frames.\")\n\nexcept Exception as e:\n    print(f\"Could not run PIMS quickstart example: {e}\")\n    print(\"Ensure test_images/ directory and dummy images exist or necessary reader dependencies are installed.\")\n","lang":"python","description":"This quickstart demonstrates how to open a sequence of image files using `pims.open`, access individual frames, iterate through the sequence, and use NumPy-like slicing. It includes a basic setup to create dummy image files if Pillow is available."},"warnings":[{"fix":"Ensure `Pillow` or `tifffile` are installed: `pip install Pillow tifffile`. If still encountering issues, consider converting problematic TIFF files to a format supported by other PIMS readers or using specific PIMS readers like `pims.TiffStack_tifffile`.","message":"PIMS v0.7 removed direct support for `libtiff`. Users who relied on `libtiff` for specific TIFF functionalities might need to ensure `Pillow` or `tifffile` are installed, or switch to other readers. This can lead to `ImportError` or `No reader found` messages for certain TIFF files.","severity":"breaking","affected_versions":">=0.7"},{"fix":"Review `numpy 2.0` migration guides (e.g., from NumPy official docs). If other dependencies are not yet compatible, you might need to pin an older `numpy` version (e.g., `numpy<2.0`) in your environment until all libraries are updated. Use `ruff` with the `NPY201` rule for automatic code adaptation if applicable to your project.","message":"PIMS v0.7 introduced compatibility with `numpy 2.0`. While this ensures PIMS works with the latest NumPy, other libraries in your environment might not yet be compatible, leading to unexpected behavior or errors related to array data types or API changes in `numpy 2.0`.","severity":"breaking","affected_versions":">=0.7"},{"fix":"Migrate your code to use PIMS pipelines. For grayscale conversion, use `pims.as_grey(reader_object)`. For custom processing, define a function and decorate it with `@pims.pipeline`.","message":"In PIMS v0.5, the `process_func`, `dtype`, and `as_grey` keyword arguments were removed from readers. These functionalities are now handled through PIMS's pipeline system, which offers lazy evaluation and more flexible processing.","severity":"breaking","affected_versions":">=0.5"},{"fix":"Install the necessary optional dependencies based on the file types you need to read. For video files, `pip install imageio-ffmpeg` or `pip install pyav` is often required. For Bio-formats, install `jpype1`. Refer to the PIMS documentation for a full list of format-specific dependencies.","message":"PIMS relies on optional external libraries for specific file formats (e.g., video, microscopy files). Without these dependencies, PIMS might fail to open certain files with an 'ImportError' or 'No reader found' message, even if PIMS itself is installed.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If you have a list of individual file paths, you should pass a glob pattern (e.g., `'*.png'`) to `pims.open()` or use `pims.ImageSequence()` if you want to explicitly create a sequence from a list of paths. For example, `pims.open(f'{directory_path}/*.png')` or `pims.ImageSequence(list_of_filepaths)`.","cause":"The `pims.open()` function expects a single string (filename, glob pattern, or directory path) or an `os.PathLike` object, but it was passed a Python list of strings.","error":"TypeError: expected str, bytes or os.PathLike object, not list"},{"fix":"Install the missing dependency using pip or conda, as specified in the error message or PIMS documentation. For example, if it's for video, `pip install imageio-ffmpeg`.","cause":"PIMS attempted to open a file type that requires an optional dependency (e.g., `PyAV` for videos, `jpype1` for Bio-formats), but that dependency is not installed in your environment.","error":"ImportError: This reader requires {dependency_name}."},{"fix":"Verify the file format is supported by PIMS. Ensure all necessary optional dependencies (e.g., `imageio-ffmpeg` for videos, `Pillow` for certain image types, `jpype1` for microscopy) are installed. If the format is less common, you might need to explicitly specify a reader (e.g., `pims.TiffStack(filename)`) or implement a custom reader.","cause":"PIMS could not automatically determine a suitable reader for the given file or pattern, likely due to an unsupported format or missing optional dependencies for the detected format.","error":"No reader found for {filename}"}]}