transformers.js/pr_1452/en/api/utils/image.md

# utils/image

Helper module for image processing.

These functions and classes are only used internally,
meaning an end-user shouldn't need to access anything here.


* [utils/image](#module_utils/image)
    * _static_
        * [.RawImage](#module_utils/image.RawImage)
            * [`new RawImage(data, width, height, channels)`](#new_module_utils/image.RawImage_new)
            * _instance_
                * [`.size`](#module_utils/image.RawImage+size) ⇒ <code>*</code>
                * [`.grayscale()`](#module_utils/image.RawImage+grayscale) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.rgb()`](#module_utils/image.RawImage+rgb) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.rgba()`](#module_utils/image.RawImage+rgba) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.putAlpha(mask)`](#module_utils/image.RawImage+putAlpha) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.resize(width, height, options)`](#module_utils/image.RawImage+resize) ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)
                * [`.split()`](#module_utils/image.RawImage+split) ⇒ [<code>Array.&lt;RawImage&gt;</code>](#RawImage)
                * [`.clone()`](#module_utils/image.RawImage+clone) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.convert(numChannels)`](#module_utils/image.RawImage+convert) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.save(path)`](#module_utils/image.RawImage+save)
            * _static_
                * [`.read(input)`](#module_utils/image.RawImage.read) ⇒ <code>*</code>
                * [`.fromCanvas(canvas)`](#module_utils/image.RawImage.fromCanvas) ⇒ [<code>RawImage</code>](#RawImage)
                * [`.fromURL(url)`](#module_utils/image.RawImage.fromURL) ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)
                * [`.fromBlob(blob)`](#module_utils/image.RawImage.fromBlob) ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)
                * [`.fromTensor(tensor)`](#module_utils/image.RawImage.fromTensor)
        * [`.load_image`](#module_utils/image.load_image)
    * _inner_
        * [`~CONTENT_TYPE_MAP`](#module_utils/image..CONTENT_TYPE_MAP)


* * *

<a id="module_utils/image.RawImage" class="group"></a>

## utils/image.RawImage

**Kind**: static class of [<code>utils/image</code>](#module_utils/image)  

* [.RawImage](#module_utils/image.RawImage)
    * [`new RawImage(data, width, height, channels)`](#new_module_utils/image.RawImage_new)
    * _instance_
        * [`.size`](#module_utils/image.RawImage+size) ⇒ <code>*</code>
        * [`.grayscale()`](#module_utils/image.RawImage+grayscale) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.rgb()`](#module_utils/image.RawImage+rgb) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.rgba()`](#module_utils/image.RawImage+rgba) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.putAlpha(mask)`](#module_utils/image.RawImage+putAlpha) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.resize(width, height, options)`](#module_utils/image.RawImage+resize) ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)
        * [`.split()`](#module_utils/image.RawImage+split) ⇒ [<code>Array.&lt;RawImage&gt;</code>](#RawImage)
        * [`.clone()`](#module_utils/image.RawImage+clone) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.convert(numChannels)`](#module_utils/image.RawImage+convert) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.save(path)`](#module_utils/image.RawImage+save)
    * _static_
        * [`.read(input)`](#module_utils/image.RawImage.read) ⇒ <code>*</code>
        * [`.fromCanvas(canvas)`](#module_utils/image.RawImage.fromCanvas) ⇒ [<code>RawImage</code>](#RawImage)
        * [`.fromURL(url)`](#module_utils/image.RawImage.fromURL) ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)
        * [`.fromBlob(blob)`](#module_utils/image.RawImage.fromBlob) ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)
        * [`.fromTensor(tensor)`](#module_utils/image.RawImage.fromTensor)


* * *

<a id="new_module_utils/image.RawImage_new" class="group"></a>

### `new RawImage(data, width, height, channels)`

Create a new `RawImage` object.

<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>data</td><td><code>Uint8ClampedArray</code> | <code>Uint8Array</code></td><td><p>The pixel data.</p>
</td>
    </tr><tr>
    <td>width</td><td><code>number</code></td><td><p>The width of the image.</p>
</td>
    </tr><tr>
    <td>height</td><td><code>number</code></td><td><p>The height of the image.</p>
</td>
    </tr><tr>
    <td>channels</td><td><code>1</code> | <code>2</code> | <code>3</code> | <code>4</code></td><td><p>The number of channels.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage+size" class="group"></a>

### `rawImage.size` ⇒ <code>*</code>

Returns the size of the image (width, height).

**Kind**: instance property of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: <code>*</code> - The size of the image (width, height).  

* * *

<a id="module_utils/image.RawImage+grayscale" class="group"></a>

### `rawImage.grayscale()` ⇒ [<code>RawImage</code>](#RawImage)

Convert the image to grayscale format.

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - `this` to support chaining.  

* * *

<a id="module_utils/image.RawImage+rgb" class="group"></a>

### `rawImage.rgb()` ⇒ [<code>RawImage</code>](#RawImage)

Convert the image to RGB format.

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - `this` to support chaining.  

* * *

<a id="module_utils/image.RawImage+rgba" class="group"></a>

### `rawImage.rgba()` ⇒ [<code>RawImage</code>](#RawImage)

Convert the image to RGBA format.

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - `this` to support chaining.  

* * *

<a id="module_utils/image.RawImage+putAlpha" class="group"></a>

### `rawImage.putAlpha(mask)` ⇒ [<code>RawImage</code>](#RawImage)

Apply an alpha mask to the image. Operates in place.

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - The masked image.  
**Throws**:

- <code>Error</code> If the mask is not the same size as the image.
- <code>Error</code> If the image does not have 4 channels.
- <code>Error</code> If the mask is not a single channel.

<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>mask</td><td><code><a href="#RawImage">RawImage</a></code></td><td><p>The mask to apply. It should have a single channel.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage+resize" class="group"></a>

### `rawImage.resize(width, height, options)` ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)

Resize the image to the given dimensions. This method uses the canvas API to perform the resizing.

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>Promise.&lt;RawImage&gt;</code>](#RawImage) - `this` to support chaining.  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>width</td><td><code>number</code></td><td><p>The width of the new image. <code>null</code> or <code>-1</code> will preserve the aspect ratio.</p>
</td>
    </tr><tr>
    <td>height</td><td><code>number</code></td><td><p>The height of the new image. <code>null</code> or <code>-1</code> will preserve the aspect ratio.</p>
</td>
    </tr><tr>
    <td>options</td><td><code>Object</code></td><td><p>Additional options for resizing.</p>
</td>
    </tr><tr>
    <td>[options.resample]</td><td><code>0</code> | <code>1</code> | <code>2</code> | <code>3</code> | <code>4</code> | <code>5</code> | <code>string</code></td><td><p>The resampling method to use.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage+split" class="group"></a>

### `rawImage.split()` ⇒ [<code>Array.&lt;RawImage&gt;</code>](#RawImage)

Split this image into individual bands. This method returns an array of individual image bands from an image.
For example, splitting an "RGB" image creates three new images each containing a copy of one of the original bands (red, green, blue).

Inspired by PIL's `Image.split()` [function](https://pillow.readthedocs.io/en/latest/reference/Image.html#PIL.Image.Image.split).

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>Array.&lt;RawImage&gt;</code>](#RawImage) - An array containing bands.  

* * *

<a id="module_utils/image.RawImage+clone" class="group"></a>

### `rawImage.clone()` ⇒ [<code>RawImage</code>](#RawImage)

Clone the image

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - The cloned image  

* * *

<a id="module_utils/image.RawImage+convert" class="group"></a>

### `rawImage.convert(numChannels)` ⇒ [<code>RawImage</code>](#RawImage)

Helper method for converting image to have a certain number of channels

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - `this` to support chaining.  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>numChannels</td><td><code>number</code></td><td><p>The number of channels. Must be 1, 3, or 4.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage+save" class="group"></a>

### `rawImage.save(path)`

Save the image to the given path.

**Kind**: instance method of [<code>RawImage</code>](#module_utils/image.RawImage)  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>path</td><td><code>string</code></td><td><p>The path to save the image to.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage.read" class="group"></a>

### `RawImage.read(input)` ⇒ <code>*</code>

Helper method for reading an image from a variety of input types.

**Kind**: static method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: <code>*</code> - The image object.

**Example:** Read image from a URL.
```javascript
let image = await RawImage.read('https://huggingface.co/datasets/Xenova/transformers.js-docs/resolve/main/football-match.jpg');
// RawImage 
```  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>input</td><td><code><a href="#RawImage">RawImage</a></code> | <code>string</code> | <code>URL</code> | <code>Blob</code> | <code>HTMLCanvasElement</code> | <code>OffscreenCanvas</code></td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage.fromCanvas" class="group"></a>

### `RawImage.fromCanvas(canvas)` ⇒ [<code>RawImage</code>](#RawImage)

Read an image from a canvas.

**Kind**: static method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>RawImage</code>](#RawImage) - The image object.  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>canvas</td><td><code>HTMLCanvasElement</code> | <code>OffscreenCanvas</code></td><td><p>The canvas to read the image from.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage.fromURL" class="group"></a>

### `RawImage.fromURL(url)` ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)

Read an image from a URL or file path.

**Kind**: static method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>Promise.&lt;RawImage&gt;</code>](#RawImage) - The image object.  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>url</td><td><code>string</code> | <code>URL</code></td><td><p>The URL or file path to read the image from.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage.fromBlob" class="group"></a>

### `RawImage.fromBlob(blob)` ⇒ [<code>Promise.&lt;RawImage&gt;</code>](#RawImage)

Helper method to create a new Image from a blob.

**Kind**: static method of [<code>RawImage</code>](#module_utils/image.RawImage)  
**Returns**: [<code>Promise.&lt;RawImage&gt;</code>](#RawImage) - The image object.  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>blob</td><td><code>Blob</code></td><td><p>The blob to read the image from.</p>
</td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.RawImage.fromTensor" class="group"></a>

### `RawImage.fromTensor(tensor)`

Helper method to create a new Image from a tensor

**Kind**: static method of [<code>RawImage</code>](#module_utils/image.RawImage)  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>tensor</td><td><code><a href="#Tensor">Tensor</a></code></td>
    </tr>  </tbody>
</table>


* * *

<a id="module_utils/image.load_image" class="group"></a>

## `utils/image.load_image`

Helper function to load an image from a URL, path, etc.

**Kind**: static constant of [<code>utils/image</code>](#module_utils/image)  

* * *

<a id="module_utils/image..CONTENT_TYPE_MAP" class="group"></a>

## `utils/image~CONTENT_TYPE_MAP`

Mapping from file extensions to MIME types.

**Kind**: inner constant of [<code>utils/image</code>](#module_utils/image)  

* * *



<EditOnGithub source="https://github.com/huggingface/transformers.js/blob/main/docs/source/api/utils/image.md" />