> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/imengine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.navigaglobal.com/imengine/usage/image.md).

# Image

Imengine is a relatively "dumb" service and will only do what you tell it to do. To generate an image you need to provide

* a [source of origin](/imengine/usage/image.md#source-of-origin),
* a crop [function](/imengine/usage/image.md#functions).

Each origin and function has it's own set of parameters described below.

These parameters are optional and general for all API, to control the output format:

| Parameter | Accepted values | Default | Description                                |
| --------- | --------------- | :-----: | ------------------------------------------ |
| *format*  | **string**      |   jpg   | Format of the resulting image. (jpg, png)  |
| *q*       | **percent**     |    60   | The quality of the resulting image (1-100) |

## Source of origin

## Image from Open Content

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?uuid={uuid}&type=preview&...`

The most common source of images is Open Content. The parameter for the source of image is mandatory and is represented by these options.

#### Query Parameters

| Name   | Type    | Description                                                                                                                           |
| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| uuid   | string  | Uuid of the image to query Open Content for.                                                                                          |
| source | boolean | In rare cases Imengine will have access to. the original version of the image, and can use that instead of the preview. Default=false |
| type   | string  | What Open Content image file to use as source. Default=preview                                                                        |

{% tabs %}
{% tab title="200 Image from Open Content." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in Open Content, or the specific Imengine don't have permission to see it." %}

```
```

{% endtab %}
{% endtabs %}

## External image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?imgsrc={imgsrc}&...`

Will create, fetch, cache and use the external image.

#### Query Parameters

| Name         | Type   | Description                                         |
| ------------ | ------ | --------------------------------------------------- |
| sourceformat | string | St the format of the external image. Default is jpg |
| imgsrc       | string | Decoded url for the external image to fetch.        |

{% tabs %}
{% tab title="200 The external image, served from imengine instead of original source." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

## Functions

Imengine offers a number of functions for manipulating images. Each function comes with it's own set of parameters. Source of origin also needs to be specified on all calls.

## Crop cover image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=cover`

Takes the original image ratio and customise the width and height to keep original ratio of the image.

#### Query Parameters

| Name   | Type    | Description                    |
| ------ | ------- | ------------------------------ |
| width  | integer | Width of the resulting image.  |
| height | integer | Height of the resulting image. |

{% tabs %}
{% tab title="200 The cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine.example.com/?uuid={uuid}&type=preview&function=cover&height=400&width=300
```

![Cover examples](/files/-MAVNQgR3RwDVMcgZR7C)

## Crop resize image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/&function=cropresize`

This function is typically used together with the NewsML article document data created with Naviga Creation tools.\
\
Crops image into defined crop size from custom start position. Then scale into defined size.

#### Query Parameters

| Name    | Type    | Description                                                                                     |
| ------- | ------- | ----------------------------------------------------------------------------------------------- |
| crop\_w | number  | Width of the soft crop in percent of the original image.                                        |
| crop\_h | number  | Height of the soft crop in percentage of the original image.                                    |
| width   | integer | Width of the resulting image.                                                                   |
| height  | integer | Height of the resulting image.                                                                  |
| x       | number  | Horisontal start position for the soft crop, as percentage of the original image from the left. |
| y       | number  | Vertical start position for the soft crop, as percentage of the original image from the top.    |

{% tabs %}
{% tab title="200 The cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine.example.com/?uuid={uuid}&type=preview&function=cropresize&crop_w=0.99999&crop_h=0.6015&width=900&height=360&x=1.0E-5&y=1.0E-5
```

![Cropresize examples](/files/-MAVSaMMSHcGixx8RNM7)

## Crop fit image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=fit`

Scale image to fit inside the limits. Add scale up to make the image cover the max size area. Can exceed limits on scale up.

#### Query Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| maxsize | integer | Height and width limit for the resulting image. |
| scaleup | boolean | Whether to exceed limits on the larger side.    |

{% tabs %}
{% tab title="200 The cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine.example.com/?uuid={uuid}&type=preview&function=fit&maxsize=1200&scaleup=true
```

![Fix examples](/files/-MAVXe_oDv-kVNGx_obd)

## Hard crop image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=hardcrop`

Crop image into defined size, from top left.

#### Query Parameters

| Name   | Type    | Description                |
| ------ | ------- | -------------------------- |
| height | integer | Height of resulting image. |
| width  | integer | Width of resulting image.  |

{% tabs %}
{% tab title="200 The cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine.example.com/?uuid={uuid}&type=preview&function=hardcrop&height=600&width=900
```

![Hardcrop examples](/files/-MAVcZp9Nae5dya33IiW)

## NP crop image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=np_crop`

This crop function is typically used by Naviga Newspilot. Crops image into defined size from custom start position.

#### Query Parameters

| Name   | Type    | Description                                                                                 |
| ------ | ------- | ------------------------------------------------------------------------------------------- |
| height | integer | Height of the resulting cropped image.                                                      |
| width  | integer | Width of the resulting cropped image.                                                       |
| x      | integer | Horisontal start position for soft crop, as percentage of the original image from the left. |
| y      | integer | Vertical start position for soft crop, as percentage of the original image from the top.    |
| zoom   | number  | Zoom of soft crop.                                                                          |

{% tabs %}
{% tab title="200 Cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image don't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine-domain/imengine/?uuid={uuid}&type=preview&function=np_crop&width=900&height=360&x=20&y=10&zoom=0.5
```

## Original image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=original`

Just fetch the image with original size. No crop, no other parameters.

{% tabs %}
{% tab title="200 Original image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image doesn't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine.example.com/?uuid={uuid}&type=preview&function=original
```

![Original example](/files/-MAVecP27jrdEr8caR0x)

## Square crop image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=square`

Crop image into a square using hardcrop.

#### Query Parameters

| Name  | Type    | Description                              |
| ----- | ------- | ---------------------------------------- |
| width | integer | Width and height of the resulting image. |

{% tabs %}
{% tab title="200 Cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image doesn't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```http
https://imengine.example.com/?uuid={uuid}&type=preview&function=square&width=120
```

![Square example](/files/-MAVfYTFAXwyEsO4sOLg)

## Thumbnail crop image

<mark style="color:blue;">`GET`</mark> `https://imengine.example.com/?function=thumbnail`

Crop image into defined size from center position.

#### Query Parameters

| Name   | Type    | Description                |
| ------ | ------- | -------------------------- |
| height | integer | Height of resulting image. |
| width  | integer | Width of resulting image.  |

{% tabs %}
{% tab title="200 Cropped image." %}

```
[image]
```

{% endtab %}

{% tab title="404 Image doesn't exist in source." %}

```
```

{% endtab %}
{% endtabs %}

Examples:

```
https://imengine.example.com/?uuid={uuid}&type=preview&function=thumbnail&height=600&width=900
```

![Thumbnail examples](/files/-MAVhulJrdHFK1osFFVv)