---
title: "ClikaRT::processor::ImageProcessor"
sidebar_label: "ImageProcessor"
description: "A config-driven static image preprocessor. Move-only. Every fallible operation returns Result<T>; the library never throws."
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--class">class</span>

**Header:** `ClikaRT/processor/processor.h`

A config-driven static image preprocessor. Move-only.

Every fallible operation returns [`Result`](../Result.md)`<T>`; the library never throws. Turn a failure into an exception on your own side with `.value_or_throw()`, or inspect `.ok()` / `.status()` / `.message()`.

## Static member functions

### from\_huggingface() {#from_huggingface}

<div class="api-signature">

`static` [`ImageProcessor`](./ImageProcessor.md) **`from_huggingface`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::string_view>` `consumed_keys` `=` `{}`<br />
)

</div>

Load a HuggingFace image preprocessor (`preprocessor_config.json`). `path` is the model directory OR the json file itself (its parent directory is used). `where` binds the default placement for [`process`](./ImageProcessor.md#process). `path` is copied, not retained.

HuggingFace-file semantics (see [`ImageProcessorConfig::from_json`](./ImageProcessorConfig.md#from_json), the parse this loader runs): a missing key takes [ClikaRT](../../index.md)'s documented default, not the per-processor-class default the file's `image_processor_type` would imply in HuggingFace; an unrecognized KEY is ignored with a logged warning naming it; a recognized size key (`size` / `crop_size` / `pad_size`) whose VALUE is in an unsupported form is refused with an error naming the supported forms. Verify the effective steps with [`ImageProcessorConfig::from_json`](./ImageProcessorConfig.md#from_json)`(<file text>)` + its getters / `to_json`.

`consumed_keys` names top-level config keys the caller consumes above this processor (a model's own tiling or geometry keys); they join the recognized set, so a clean load logs no unknown-key warning. Keys neither recognized nor named still warn. Read during the call, not retained.

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 115

</div>

### from\_directory() {#from_directory}

<div class="api-signature">

`static` [`ImageProcessor`](./ImageProcessor.md) **`from_directory`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::string_view>` `consumed_keys` `=` `{}`<br />
)

</div>

Load from a model directory, detecting the preprocessor format present (currently HuggingFace). `path` is copied, not retained. `consumed_keys` extends the recognized key set exactly as on [`from_huggingface`](./ImageProcessor.md#from_huggingface); read during the call, not retained.

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 125

</div>

### from\_config() {#from_config}

<div class="api-signature">

`static` [`ImageProcessor`](./ImageProcessor.md) **`from_config`**(`const` [`ImageProcessorConfig`](./ImageProcessorConfig.md)`&` `config`, [`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`)

</div>

Build from an explicit config; no config file needed. `where` binds the default placement for [`process`](./ImageProcessor.md#process). `config` is read during the call.

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 131

</div>

### from\_args() {#from_args}

<div class="api-signature">

`static` [`ImageProcessor`](./ImageProcessor.md) **`from_args`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::optional<std::pair<std::int64_t, std::int64_t>>` `resize` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::optional<std::pair<std::int64_t, std::int64_t>>` `crop` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::optional<double>` `rescale` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::optional<`[`ClikaRT::Span`](../Span.md)`<const float>>` `mean` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::optional<`[`ClikaRT::Span`](../Span.md)`<const float>>` `std` `=` `{}`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
)

</div>

Build directly from the COMMON knobs: no config file, no config object. Pass `{}` for any knob to take its default; override only what you care about. For full control (pad, crop kinds, target dtype, resize order) build an [`ImageProcessorConfig`](./ImageProcessorConfig.md) and use [`from_config`](./ImageProcessor.md#from_config).

- `resize` `{height, width}` to resize to; `{}` = the config default (resize on, driven by the model config when loaded; here `{}` leaves resize at its default-off-for-args state, see below).
- `crop` `{height, width}` center-crop; `{}` = no crop.
- `rescale` pixel scale; `{}` = `kImageRescaleFactor` (1/255).
- `mean`/`std` per-channel normalize operands (length 1 or 3); BOTH `{}` = no normalize, BOTH present = normalize on. Read during the call.

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 145

</div>

## Member functions

### ImageProcessor() {#ImageProcessor}

<div class="api-signature">

**`ImageProcessor`**(`ImageProcessor&&`) `noexcept`

</div>

move-construct (the source becomes an empty shell)

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 161

</div>

### operator=() {#operator-assign}

<div class="api-signature">

[`ImageProcessor`](./ImageProcessor.md)`&` **`operator=`**([`ImageProcessor`](./ImageProcessor.md)`&&`) `noexcept`

</div>

move-assign

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 162

</div>

### \~ImageProcessor() {#ImageProcessor-2}

<div class="api-signature">

**`~ImageProcessor`**()

</div>

destructor

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 163

</div>

### process(string\_view, StreamOrDevice) {#process}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process`**(`std::string_view` `path`, [`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`) `const`

</div>

Preprocess one image from a file path → `[H, W, C]` Float32. `path` is read during the call, not retained. `where` overrides the bound placement (`{}` = bound).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 169

</div>

### process(Span\< uint8\_t\>, StreamOrDevice) {#process-2}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`, [`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`) `const`

</div>

Preprocess one image from a file path → `[H, W, C]` Float32. `path` is read during the call, not retained. `where` overrides the bound placement (`{}` = bound).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 173

</div>

### process(Tensor, StreamOrDevice) {#process-3}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process`**(`const` [`Tensor`](../Tensor.md)`&` `image`, [`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`) `const`

</div>

Preprocess one image from a file path → `[H, W, C]` Float32. `path` is read during the call, not retained. `where` overrides the bound placement (`{}` = bound).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 177

</div>

### process\_batch(Span\< Span\< uint8\_t\>\>, StreamOrDevice) {#process_batch}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process_batch`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const` [`ClikaRT::Span`](../Span.md)`<const std::uint8_t>>` `images`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
) `const`

</div>

Preprocess a batch of encoded images → `[N, H, W, C]` Float32 (all images must preprocess to the same `[H, W, C]`; fix the output size in the config).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 181

</div>

### process(string\_view, ImageProcessOptions, StreamOrDevice) {#process-4}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`ImageProcessOptions`](./ImageProcessOptions.md)`&` `options`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
) `const`

</div>

Preprocess one image from a file path → `[H, W, C]` Float32. `path` is read during the call, not retained. `where` overrides the bound placement (`{}` = bound).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 189

</div>

### process(Span\< uint8\_t\>, ImageProcessOptions, StreamOrDevice) {#process-5}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`ImageProcessOptions`](./ImageProcessOptions.md)`&` `options`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
) `const`

</div>

Preprocess one image from a file path → `[H, W, C]` Float32. `path` is read during the call, not retained. `where` overrides the bound placement (`{}` = bound).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 192

</div>

### process(Tensor, ImageProcessOptions, StreamOrDevice) {#process-6}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`Tensor`](../Tensor.md)`&` `image`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`ImageProcessOptions`](./ImageProcessOptions.md)`&` `options`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
) `const`

</div>

Preprocess one image from a file path → `[H, W, C]` Float32. `path` is read during the call, not retained. `where` overrides the bound placement (`{}` = bound).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 195

</div>

### process\_batch(Span\< Span\< uint8\_t\>\>, ImageProcessOptions, StreamOrDevice) {#process_batch-2}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`process_batch`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const` [`ClikaRT::Span`](../Span.md)`<const std::uint8_t>>` `images`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`ImageProcessOptions`](./ImageProcessOptions.md)`&` `options`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
) `const`

</div>

Preprocess a batch of encoded images → `[N, H, W, C]` Float32 (all images must preprocess to the same `[H, W, C]`; fix the output size in the config).

<div class="api-declared">

Declared in `ClikaRT/processor/processor.h`, line 199

</div>