> This page is for version 26.07 · v1.3.0.
> For other versions, use one of these documentation indexes:
> - Latest · v1.4.0 (26.09) (default): https://docs.nvidia.com/nemo/curator/latest/llms.txt
> - Main · preview: https://docs.nvidia.com/nemo/curator/main/llms.txt
> - 26.09 · v1.4.0: https://docs.nvidia.com/nemo/curator/v26.09/llms.txt
> - 26.07 · v1.3.0: https://docs.nvidia.com/nemo/curator/v26.07/llms.txt
> - 26.04 · v1.2.0: https://docs.nvidia.com/nemo/curator/v26.04/llms.txt
> - 26.02 · v1.1.0: https://docs.nvidia.com/nemo/curator/v26.02/llms.txt
> - 25.09 · v1.0.0: https://docs.nvidia.com/nemo/curator/v25.09/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/curator/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/curator/_mcp/server.

# ImageBatch

> API reference for ImageBatch - the task type for image processing

`ImageBatch` is the task type for image processing in NeMo Curator.

## Import

```python
from nemo_curator.tasks import ImageBatch
```

## Class Definition

```python
from dataclasses import dataclass
from nemo_curator.tasks.image import ImageObject

@dataclass
class ImageBatch(Task[list[ImageObject]]):
    """Task containing a batch of images.

    Attributes:
        task_id: Framework-managed deterministic lineage identifier.
        dataset_name: Name of the source dataset.
        data: List of ImageObject instances.
    """

    dataset_name: str
    data: list[ImageObject]
    # task_id is inherited from Task with init=False.
```

## ImageObject

Each image in the batch is represented by an `ImageObject`:

```python
@dataclass
class ImageObject:
    """Represents a single image with metadata.

    Attributes:
        path: Path to the image file.
        caption: Optional text caption for the image.
        metadata: Additional metadata dictionary.
        embeddings: Optional embedding vector.
    """

    path: str
    caption: str | None = None
    metadata: dict[str, Any] = field(default_factory=dict)
    embeddings: np.ndarray | None = None
```

## Properties

### `num_items`

Get the number of images in the batch.

```python
@property
def num_items(self) -> int:
    """Returns the number of images in this batch."""
```

## Creating ImageBatch

```python
from nemo_curator.tasks import ImageBatch
from nemo_curator.tasks.image import ImageObject

# Create image objects
images = [
    ImageObject(
        path="/data/images/image1.jpg",
        caption="A cat sitting on a couch",
        metadata={"source": "dataset_a"},
    ),
    ImageObject(
        path="/data/images/image2.jpg",
        caption="A dog playing in the park",
        metadata={"source": "dataset_a"},
    ),
]

# Create batch
batch = ImageBatch(
    dataset_name="image_dataset",
    data=images,
)
```

Do not pass `task_id` to the constructor. The framework assigns it after the task crosses a stage boundary.

## Usage in Stages

```python
from dataclasses import dataclass
from nemo_curator.stages.base import ProcessingStage
from nemo_curator.tasks import ImageBatch

@dataclass
class ImageFilterStage(ProcessingStage[ImageBatch, ImageBatch]):
    """Filter images based on metadata."""

    name: str = "ImageFilter"
    min_resolution: int = 256

    def inputs(self) -> tuple[list[str], list[str]]:
        return ["data"], []

    def outputs(self) -> tuple[list[str], list[str]]:
        return ["data"], []

    def process(self, task: ImageBatch) -> ImageBatch | None:
        filtered = [
            img for img in task.data
            if img.metadata.get("width", 0) >= self.min_resolution
            and img.metadata.get("height", 0) >= self.min_resolution
        ]

        if not filtered:
            return None

        return ImageBatch(
            dataset_name=task.dataset_name,
            data=filtered,
            _metadata=task._metadata,
            _stage_perf=task._stage_perf,
        )
```

## Common Operations

### Adding Embeddings

```python
def process(self, task: ImageBatch) -> ImageBatch:
    for img in task.data:
        img.embeddings = self.model.encode(img.path)

    return ImageBatch(
        dataset_name=task.dataset_name,
        data=task.data,
        _metadata=task._metadata,
        _stage_perf=task._stage_perf,
    )
```

### Filtering by Score

```python
def process(self, task: ImageBatch) -> ImageBatch | None:
    filtered = [
        img for img in task.data
        if img.metadata.get("aesthetic_score", 0) >= self.threshold
    ]

    if not filtered:
        return None

    return ImageBatch(
        dataset_name=task.dataset_name,
        data=filtered,
        _metadata=task._metadata,
        _stage_perf=task._stage_perf,
    )
```

## Source Code

[View source on GitHub](https://github.com/NVIDIA-NeMo/Curator/blob/main/nemo_curator/tasks/image.py)