ImageReader Plugin ¶

Description ¶

The ImageReader plugin provides specialized image input capabilities for CVEDIA-RT, designed to handle static image files and image sequences. It enables seamless integration of image-based workflows into video processing pipelines with comprehensive format support and batch processing capabilities.

ImageReader acts as a versatile image input solution that can process individual images or entire directories of images as pseudo-video sequences. It provides efficient memory management, automatic format detection, and flexible processing options for various computer vision workflows.

Key capabilities include:

Multi-format image file support (JPEG, PNG, BMP, TIFF, etc.)
Directory-based image sequence processing
Automatic format detection and validation
Memory-optimized image loading
Frame-based navigation through image sequences
Integration with video processing pipelines
Batch processing for large image datasets

Requirements ¶

Software Dependencies ¶

OpenCV: Required for image decoding and format support
Image Format Libraries: JPEG, PNG, TIFF libraries for extended format support
CVEDIA-RT Core: Base runtime functionality

Supported Image Formats ¶

JPEG (.jpg, .jpeg) - Joint Photographic Experts Group format
PNG (.png) - Portable Network Graphics format
BMP (.bmp) - Windows Bitmap format
TIFF (.tiff, .tif) - Tagged Image File Format
Additional formats supported by OpenCV backend

Configuration ¶

Basic Configuration ¶

{
  "input": {
    "handlers": {
      "image-input": {
        "uri": "file:///path/to/image.jpg",
        "plugin": "ImageReader",
        "enabled": true
      }
    }
  }
}

Image Sequence Configuration ¶

{
  "input": {
    "handlers": {
      "image-sequence": {
        "uri": "file:///path/to/images/",
        "plugin": "ImageReader",
        "start_frame": 0,
        "end_frame": 100,
        "repeat": true,
        "enabled": true
      }
    }
  }
}

Advanced Configuration ¶

{
  "input": {
    "handlers": {
      "image-input": {
        "uri": "file:///path/to/images/",
        "plugin": "ImageReader",
        "start_frame": 10,
        "end_frame": 500,
        "repeat": false,
        "input_format": {
          "use_default_format": false,
          "height": 720,
          "width": 1280
        },
        "enabled": true
      }
    }
  }
}

Configuration Parameters ¶

Parameter	Type	Default	Description
`uri`	string	-	Image file path or directory path containing images
`start_frame`	integer	0	Starting frame index for image sequences
`end_frame`	integer	0	Ending frame index (0 = process all images)
`repeat`	boolean	false	Loop through image sequence when end is reached
`input_format.use_default_format`	boolean	true	Use automatic format detection
`input_format.height`	integer	-	Target height for image resizing
`input_format.width`	integer	-	Target width for image resizing

Supported URIs ¶

The ImageReader plugin supports various URI formats:

Single Image: file:///path/to/image.jpg
Image Directory: file:///path/to/images/
Relative Paths: images/sample.png (relative to project path)
Absolute Paths: Direct file system paths

API Reference ¶

Core Classes ¶

ImageReaderCore ¶

Main implementation class providing image reading functionality:

class ImageReaderCore {
public:
    struct config {
        int start_frame = 0;    // Starting frame for sequences
        int end_frame = 0;      // End frame (0 = all frames)
    };

    struct stats {
        int input_width = 0;
        int input_height = 0;
        int current_frame = 0;
        int total_frames = 0;
        std::string current_uri;
    };

    // Core methods
    expected<cvec> getNextFrame(bool ignoreSkipFrame = false);
    void setCurrentFrame(int frameNum);
    int getCurrentFrame() const;
    int getFrameCount() const;
    double getCurrentTimestamp() const;

    // Control methods
    bool isEnded() const;
    void setRepeat(bool repeat);
    bool willRepeat() const;
    bool canRead() const;

    // Input handling
    expected<void> openUri(std::string const& uri, std::string const& project_path = "");
    std::vector<InputFormat> getSourceFormats();
    void setSourceDefaultFormat(InputFormat fmt);
    InputFormat getSourceDefaultFormat();
};

ImageReaderHandler ¶

Managed interface implementing the ImageReader interface:

class ImageReaderHandler final : public iface::ImageReader {
public:
    static std::unique_ptr<iface::ImageReader> create(std::string const& moduleName);

    // Frame navigation
    int getCurrentFrameIndex() override;
    int getFrameCount() override;
    double getCurrentTimestamp() override;

    // Playback control
    bool canRead() override;
    void setRepeat(bool repeat) override;
    bool willRepeat() override;

    // Input operations
    expected<void> openUri(std::string const& uri) override;
    expected<cvec> readFrame(bool ignore_skip_frame = false, cmap frameSettings = {}) override;

    // Format handling
    std::vector<InputFormat> getSupportedFormats() override;
    void setSourceFormat(InputFormat fmt) override;
    InputFormat getSourceFormat() override;
};

Key Features ¶

Directory Processing: Automatically discovers and sorts images in directories
Format Support: Leverages OpenCV for comprehensive image format support
Memory Management: Efficient loading and processing of large image datasets
Frame Navigation: Provides video-like navigation through image sequences
Repeat Mode: Configurable looping for continuous processing
Resize Support: Optional image resizing during loading

Examples ¶

Single Image Processing ¶

{
  "input": {
    "handlers": {
      "single-image": {
        "uri": "file:///data/sample.jpg",
        "plugin": "ImageReader",
        "enabled": true
      }
    }
  }
}

Image Sequence Processing ¶

{
  "input": {
    "handlers": {
      "image-sequence": {
        "uri": "file:///data/images/",
        "plugin": "ImageReader",
        "start_frame": 0,
        "end_frame": 0,
        "repeat": true,
        "enabled": true
      }
    }
  }
}

Batch Processing with Frame Range ¶

{
  "input": {
    "handlers": {
      "batch-processing": {
        "uri": "file:///data/dataset/",
        "plugin": "ImageReader",
        "start_frame": 100,
        "end_frame": 500,
        "repeat": false,
        "enabled": true
      }
    }
  }
}

Image Resizing ¶

{
  "input": {
    "handlers": {
      "resized-images": {
        "uri": "file:///data/high_res_images/",
        "plugin": "ImageReader",
        "input_format": {
          "use_default_format": false,
          "height": 720,
          "width": 1280
        },
        "enabled": true
      }
    }
  }
}

Performance Considerations ¶

Memory Management ¶

Images are loaded on-demand to minimize memory usage
Consider image resolution and batch size for memory-constrained environments
Use resize options to reduce memory footprint when full resolution is not required

Processing Optimization ¶

Directory scanning is performed once during initialization
Images are sorted alphabetically for predictable processing order
Frame skipping and range selection can improve processing performance

Large Dataset Handling ¶

Use start_frame and end_frame parameters to process subsets
Consider splitting large directories into smaller batches
Monitor memory usage with high-resolution images

Troubleshooting ¶

Common Issues ¶

Image Not Found

Error: DoesNotExist

- Verify the file path exists and is accessible - Check file permissions - Ensure the image format is supported

Failed to Read Image

Error: ReadFailed

- Verify the image file is not corrupted - Check if the image format is supported by OpenCV - Ensure sufficient disk space and memory

Empty Directory

Found 0 images

- Verify the directory contains supported image formats - Check file extensions (currently supports .jpg, .jpeg, .png) - Ensure directory permissions allow reading

Memory Issues - Reduce image resolution using input format parameters - Process images in smaller batches - Consider using frame range selection

Debug Tips ¶

Enable verbose logging to see image discovery process
Check the total_frames statistic to verify image count
Monitor current_frame to track processing progress
Use single image processing to isolate format issues