Python Image Sequence (PIMS)

Common errors

• TypeError: expected str, bytes or os.PathLike object, not list

  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.
  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)`.

• ImportError: This reader requires {dependency_name}.

  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.
  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`.

• No reader found for {filename}

  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.
  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.

Warnings

• breaking 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.
  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`.
• breaking 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`.
  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.
• breaking 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.
  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`.
• gotcha 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.
  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.

Install

• pip install pims Basic Installation
• pip install pims[all] With common optional dependencies (ffmpeg, imageio, Pillow, PyAV, scikit-image)
• pip install pims imageio-ffmpeg For video support (recommended alternative to pims[all])

Imports

• open

  import pims
  images = pims.open('path/to/files/*.tif')

• ImageSequence

  from pims import ImageSequence
  images = ImageSequence('path/to/images/*.png')

• as_grey

  from pims import as_grey, open
  colored_images = pims.open('path/to/color_images/*.tif')
  greyscale_images = as_grey(colored_images)

Quickstart

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.

import pims
import numpy as np
import os

# Create dummy image files for demonstration
if not os.path.exists('test_images'):
    os.makedirs('test_images')
for i in range(5):
    # Using a minimal image writing approach or mocking if actual image lib is heavy
    # For real use, ensure Pillow or scikit-image is installed.
    try:
        from PIL import Image
        img = Image.new('L', (10, 10), color = i * 50)
        img.save(f'test_images/frame_{i:02d}.png')
    except ImportError:
        print("Pillow not found, cannot create dummy images. Skipping image creation.")
        break

# Open a sequence of images
try:
    frames = pims.open('test_images/frame_*.png')
    print(f"Opened sequence with {len(frames)} frames.")
    
    # Access a single frame (lazy loading)
    first_frame = frames[0]
    print(f"Shape of the first frame: {first_frame.shape}")
    print(f"Pixel value at (0,0) in first frame: {first_frame[0, 0]}")
    
    # Iterate through frames
    sum_pixels = 0
    for frame in frames:
        sum_pixels += np.sum(frame)
    print(f"Total sum of all pixel values: {sum_pixels}")

    # Slicing returns another lazy-loading object
    sub_sequence = frames[1:4]
    print(f"Sub-sequence has {len(sub_sequence)} frames.")

    # Example with a specific reader (if 'test_tiff.tif' existed)
    # from pims import TiffStack
    # tiff_stack = TiffStack('test_tiff.tif')
    # print(f"Tiff stack has {len(tiff_stack)} frames.")

except Exception as e:
    print(f"Could not run PIMS quickstart example: {e}")
    print("Ensure test_images/ directory and dummy images exist or necessary reader dependencies are installed.")