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

# nemo_automodel.components.datasets.diffusion.multi_tier_bucketing

## Module Contents

### Classes

| Name                                                                                                                        | Description                                                         |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`MultiTierBucketCalculator`](#nemo_automodel-components-datasets-diffusion-multi_tier_bucketing-MultiTierBucketCalculator) | Calculate resolution buckets constrained by a maximum pixel budget. |

### Data

[`logger`](#nemo_automodel-components-datasets-diffusion-multi_tier_bucketing-logger)

### API

```python
class nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator(
    quantization: int = 64,
    max_pixels: typing.Optional[int] = None,
    debug_mode: bool = False
)
```

Calculate resolution buckets constrained by a maximum pixel budget.
Supports various aspect ratios, each scaled to fit within the pixel budget.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator._build_lookup_structures()
```

Build efficient lookup structures.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator._calculate_max_resolution(
    aspect_ratio: float
) -> typing.Optional[typing.Tuple[int, int]]
```

Calculate the maximum resolution for an aspect ratio within the pixel budget.

For a given aspect ratio r = w/h, and pixel budget P:
w \* h \<= P
w = r \* h
r \* h \* h \<= P
h \<= sqrt(P / r)

Then w = r \* h

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator._generate_all_buckets() -> typing.List[typing.Dict]
```

Generate all unique resolution buckets within the pixel budget.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator._print_bucket_summary()
```

Print summary of generated buckets.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator._round_to_quantization(
    value: int
) -> int
```

Round value to nearest quantization multiple.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.from_preset(
    preset: str,
    quantization: int = 64
) -> nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator
```

classmethod

Create calculator from a named preset.

**Parameters:**

One of '256p', '512p', '768p', '1024p', '1536p'

Resolution quantization

**Returns:** `MultiTierBucketCalculator`

MultiTierBucketCalculator instance

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.get_all_buckets() -> typing.List[typing.Dict]
```

Get all buckets.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.get_bucket_by_id(
    bucket_id: int
) -> typing.Dict
```

Get bucket by ID.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.get_bucket_by_resolution(
    width: int,
    height: int
) -> typing.Optional[typing.Dict]
```

Get bucket by exact resolution.

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.get_bucket_for_image(
    image_width: int,
    image_height: int
) -> typing.Dict
```

Get the best bucket for an image.

**Parameters:**

Original image width

Original image height

Override max pixels for this query (deprecated, use constructor)

**Returns:** `Dict`

Bucket dictionary with resolution and metadata

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.get_dynamic_batch_size(
    resolution: typing.Tuple[int, int],
    base_batch_size: int = 32,
    base_resolution: typing.Tuple[int, int] = (512, 512)
) -> int
```

Calculate dynamic batch size based on resolution.
Larger images get smaller batches to maintain GPU memory usage.

**Parameters:**

(width, height)

Batch size for base resolution

Reference resolution

**Returns:** `int`

Recommended batch size

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.MultiTierBucketCalculator.resize_and_crop(
    image,
    target_width: int,
    target_height: int,
    crop_mode: str = 'center'
) -> typing.Tuple
```

Resize and crop image to target resolution.

**Parameters:**

PIL Image or numpy array

Target width

Target height

'center', 'random', or 'smart'

**Returns:** `Tuple`

(resized\_image, crop\_offset\_x, crop\_offset\_y)

```python
nemo_automodel.components.datasets.diffusion.multi_tier_bucketing.logger = logging.getLogger(__name__)
```