MAX-CV Development

You are working with MAX-CV, an accelerated image processing framework built on MAX and Mojo, inspired by the GPUImage series. This framework provides a high-level Python API with Mojo-based custom operations for realtime video processing and machine vision tasks.

Primary Documentation References

Always consult these resources when working on the project:

Architecture Overview

Core Components

1. **Python API Layer** (`max_cv/`)

- `ImagePipeline`: Main class for constructing image processing graphs

- `io.py`: Image loading/saving utilities with `load_image_into_tensor()`

- `operations/`: Python wrappers invoking Mojo custom ops via `ops.custom()`

2. **Mojo Custom Operations** (`max_cv/operations_mojo/`)

- Low-level image processing operations in Mojo

- Registered with `@compiler.register("op_name")` decorator

- Uses `foreach` with element-wise kernels for GPU/CPU execution

- Organized by category: blend, color_correction, draw, edge_detection, effects, transform

3. **Pipeline Flow**

- Load images into `Buffer` objects on CPU or accelerator

- `ImagePipeline` constructs a MAX `Graph` (images normalized to 0.0-1.0 float32)

- Operations chained with `pipeline.input_image`

- Compile once with `pipeline.compile()` for optimized `Model`

- Execute multiple times with `pipeline(buffer)`

- Output automatically restored to uint8 0-255 colorspace

Essential Development Commands

Testing and Formatting

Examples and Demos

- Examples: `pixi run showcase pixellate --value 15`

- `pixi run showcase brightness --value 0.3`

- `pixi run showcase gaussian_blur --kernel_size 16 --sigma 4.0`

Code Patterns

Device Management

```python

from max.driver import Accelerator, CPU, accelerator_count

device = CPU() if accelerator_count() == 0 else Accelerator()

```

Single-Input Pipeline Construction

```python

from max_cv import ImagePipeline, load_image_into_tensor, operations as ops

from max.dtype import DType

image_tensor = load_image_into_tensor(image_path, device)

with ImagePipeline(

"pipeline_name",

image_tensor.shape,

pipeline_dtype=DType.float32,

device=device,

) as pipeline:

result = ops.brightness(device, pipeline.input_image, 0.5)

pipeline.output(result)

pipeline.compile()

result = pipeline(image_tensor)

```

Multi-Input Pipeline (Blending, etc.)

```python

with ImagePipeline(..., num_inputs=2) as pipeline:

result = ops.dissolve_blend(

device,

pipeline.input_images[0],

pipeline.input_images[1],

0.5

)

pipeline.output(result)

result = pipeline(image1_buffer, image2_buffer)

```

Buffer Handling

Custom Operation Pattern (Mojo)

```mojo

@compiler.register("operation_name")

struct OperationName:

@staticmethod

fn execute[target: StaticString](

output: OutputTensor,

param: Float32,

image: InputTensor[dtype = output.dtype, rank = output.rank],

ctx: DeviceContextPtr,

) raises:

@parameter

@always_inline

fn kernel[width: Int](idx: IndexList[image.rank]) -> SIMD[image.dtype, width]:

# Process pixels here

return image.load[width](idx) + param

foreach[kernel, target=target](output, ctx)

```

Available Operations

Color Adjustments

Edge Detection

Visual Effects

Blending (two-image operations)

Drawing

Transforms

Environment Requirements

Key Constraints