---
title: "getGeneratedImage"
slug: "api/basket/operations/getgeneratedimage"
sidebar:
  order: 454
---

<a id="ref-ac7e59acfb5c"></a>
<a id="ref-01360c8648c1"></a>
<a id="ref-02c6977fea5f"></a>

## Synopsis

```text
URL getGeneratedImage(SessionId sessionId,
    BItemId itemId,
    string[]  options)
throws BasketServiceFault;
```

See also: [URL](/pCon/configuratorOnline/specs/guide/web-service-interfaces/common-type-definitions/url#ref-e7a241debad5), [SessionId](/pCon/configuratorOnline/specs/api/session/types/sessionid#ref-02e397c8fdb4), [BItemId](/pCon/configuratorOnline/specs/api/basket/types/bitemid#ref-bccb6c926e5b), [BasketServiceFault](/pCon/configuratorOnline/specs/api/basket/faults/basketservicefault#ref-d5adb74faa1b)

The `getGeneratedImage` operation is used to compute an image for the article identified by the `itemId` parameter.

The `itemId` parameter must identify an article item that is part of the basket item tree maintained by the basket service for the session identified by the `sessionId` parameter.

The `options` parameter is a sequence consisting of zero or more option strings, where each option string consists of a key and value, separated by an equal sign (`=`) (e.g. `"format=jpg"`).

**Note:** The pCon applications use the following options for `getGeneratedImage`:

```text
"format=JPG",
"shadowPlane=true",
"shadowPlane.filter=DOF",
"shadowPlane.color=0.4 0.4 0.4",
"ambient=0.8 0.8 0.8",
"renderMode=PBR"
```

The following options are available (numbers delimited by horizontal ellipsis (…) specify minimum and maximum values, specified default values are listed below the option syntax):

### `tag=string:default`

**Default:** `default`

The value of this option must be a valid Unicode identifier. Each article item stores a reference to the last image generated for this tag and item until the configuration of the article item is changed[^1]. Furthermore, the `saveSession` (§[saveSession](/pCon/configuratorOnline/specs/api/session/operations/savesession#ref-cc7e4d5d8203)) and `loadSession` (§[loadSession](/pCon/configuratorOnline/specs/api/session/operations/loadsession#ref-dcf6596732bf)) operations of the session web service save and load these images and each (article) item’s mapping from tag to image.

An image returned by operation `getGeneratedImage` when invoked without option `tag`, with an empty tag, or with tag `default` is not used as the default generated article image for the current configuration of the article if the specified format is neither JPEG nor PNG.

### `width=int:32…512…2048`

**Default:** `512`

width of the image in pixel

If the `width` option has been specified, but not the `height` option, the specified value is used for both the width and height of the generated image. If neither option is specified, then the default image width is 512 pixels.

The `width` option must not be used if the `scale` option is used, as the `scale` option, in combination with the `margin` option, determines the width of the generated image.

For SVG, PDF, EPS and PS exports the value of `width` must be specified in point (1/72 inch). The default value is 384 pt. The maximum value is 3370 pt.

### `height=int:32…512…2048`

**Default:** `512`

height of the image in pixel

If the `height` option has been specified, but not the `width` option, the specified value is used for both the width and height of the generated image. If neither option has been specified, then the default image height is 512 pixels.

The `height` option must not be used if the `scale` option is used, as the `scale` option, in combination with the `margin` option, determines the height of the generated image.

For SVG, PDF, EPS and PS exports the value of `height` must be specified in point (1/72 inch). The default value is 384 pt. The maximum value is 3370 pt.

### `format=enum:JPG|PNG|TGA|TIFF|SVG|PDF|EPS|PS|MCP`

format of the resulting image file

The default image file format depends on whether or not the `scale` option is used. PNG is used for true to scale images, JPEG otherwise.

Note: The export of SVG, PDF, EPS and PS is on an experimental stage. Important features still missing are: transparent background, true-to-scale images. The other options supported and allowed are `width`, `height` and `hideSubArticles`. The value of `width` and `height` must be specified in point (1/72 inch). The default value is 384 pt. The  maximum value is 3370 pt.

MCP exports Multi Content Picture.

### `hideSubArticles=boolean`

Controls whether or not sub-articles of composite articles are hidden during image generation (and thus are not shown together with the composite article).

The default value depends on the exported image format. In case of `format=MCP`, the default value is `false`. In all other cases, it is `true`.

If the operation is invoked for a sub-article, then this sub-article is not hidden, regardless of the value of this option. If, however, the sub-article happens to be a composite article, then the option affects the hiding of sub-articles of this nested composite article.

### `antialias=boolean:false`

**Default:** `false`

Controls the use of an anti-aliasing algorithm during image generation.

Note that the improved image quality is achieved at the cost of image generation time (about five times slower). Especially for large images this may make a significant difference.

The default value depends on the value of the `resample` option (`true` if `resample=1`, `false` otherwise).

### `resample=int:1…2…32`

**Default:** `2`

The `resample` option allows for the rendering of the image using a resolution greater than specified by the `width` and height `options`, or computed based on the scale factor for true-to-scale images. The required width and height are multiplied by the resampling factor to determine the image dimensions used during rendering. The rendered image is scaled down by the given factor to produce an image with the required width and height.

If the image dimensions used during rendering exceed a certain limit (4096x4096 in EAIWS version 3.0), the resampling factor is reduced automatically.

Rendering with `resample=4` and `antialias=false` usually results in about the same image generation time as `resample=1` and `antialias=true` (the default behavior prior to EAIWS 3.0 RC 2), but produces better results.

### `quality=int:10…80…100`

**Default:** `80`

quality of generated JPEG image

### `ambient=float:0.0…0.2…1.0 float:0.0…0.2…1.0 float:0.0…0.2…1.0`

```text
ambient color (brightness); The individual values are for red, green and blue.
```

In case of `renderMode=PBR` the option `ambient` can be used to control the brightness of the rendered image. The default value of option `ambient` with `renderMode=PBR` is `0.75 0.75 0.75`. For other render modes the default value continues to be `0.2 0.2 0.2`.

### `background=float:0.0…1.0 float:0.0…1.0 float:0.0…1.0`

color of background; The individual values are for red, green and blue.

If the selected image format supports an alpha channel, then the special value `transparent` may be used instead of the color components to produce an image with a transparent background.

### `enable2D=boolean:false`

**Default:** `false`

If set to `true`, 2D-geometries are rendered at height zero.

For raster image formats, the `enable2D` option defaults to `false`. For vector graphics formats, the `enable2D` option defaults to `true`.

### `enable2DZBuffer=boolean:false`

**Default:** `false`

If set to `true`, the Z-buffer is enabled during rendering of 2D-geometries. Consequently, 2D-geometries may be hidden by 3D-geometries.

The value of this option is processed, but otherwise ignored, if the value of the `enable2D` option is `false`.

The default value is `false`. Setting this option to `true` should affect the generated (raster) image if and only if both 2D and 3D geometries are rendered.

### `enable3D=boolean:true`

**Default:** `true`

Controls whether or not to render 3D-geometries.

Note that the `enable2D` option must be set to `true` if this option is set to `false`. Otherwise, the operation fails.

For raster image formats, the `enable3D` option defaults to `true`. For vector graphics formats, the `enable3D` option defaults to `false`.

**layerControl**

The argument of this option must be a string that adheres to the following grammar:

layer-control = \[ global \] { specific }

global = "\\\*" \| "!"

specific = onoff layer-spec { suffix }

onoff = "\\+" \| "-"

suffix = "r" \| "i"

layer-spec = "'(\[^'\]\|'')\*'" \| "\\"(\[^\\"\]\|\\"\\")\*\\""

(Character sequences enclosed in double quotes represent terminal symbols specified as POSIX Extended Regular Expressions, with the addition that \\" represents an ordinary double quote character that does not terminate the character sequence.)

The layer control string is processed left to right. If `global` is present, all layers are initially switched on ('\*') or off ('!'). 'layer-spec' is a string whose meaning depends on the possibly empty sequence of suffixes. If the 'r' suffix is present, it is a POSIX Extended Regular Expression, selecting all layers whose complete name matches the regular expression. Otherwise it is an ordinary string that must match a complete layer name. If the 'i' suffix is present, matching is done in a case-insensitive way. It is not an error if suffixes appear more than once. Selected layers are switched on if `onoff` is '+', and off if `onoff` is '-'.

After the export, layers are switched back to their original state.

### `renderMode=enum:Textures|Color|GrayScale|BlackWhite|PBR`

**Default:** `Textures`

the rendering mode

Option `renderMode=PBR` enables Physically Based Rendering. Option `ambient` can be used to control the brightness of the rendered image. The default value of option `ambient` with `renderMode=PBR` is `0.5 0.5 0.5`. For other render modes the default value continues to be `0.2 0.2 0.2`.

### `outline=boolean:false`

**Default:** `false`

whether or not to outline edges; applies to render modes `Textures` and [`Color`](/pCon/configuratorOnline/specs/api/basket/operations/getarticlerenderingsetup#ref-6b73191a0a4b) only

### `fadeBorder=int:0…<max-value>`

**Default:** `0`

controls soft fading-out of image margin. The parameter specifies the with of the margin in pixels. *\<max-value\>* is half the minimum of the width and height of the generated image.

If the `scale` option is used to generate a true to scale image, the `fadeBorder` option has no effect, and the upper bound of the option value is not checked.

### `shadowPlane=boolean:true`

**Default:** `true`

whether or not a shadow plane will be displayed below the article.

This option is ignored and the generated image will never contain a shadow plane if the `scale` option is used to generate a true to scale image, or if the viewpoint height is less than or equal to zero.

The following options, prefixed with `shadowPlane`., are ignored if the generated image does not contain a shadow plane.

### `shadowPlane.color=float:0.0…0.5…1.0 float:0.0…0.5…1.0 float:0.0…0.5…1.0`

affects the color of the shadow plane; The individual values are for red, green and blue.

The option is ignored if the generated image does not contain a shadow plane.

In case of `shadowPlane.filter=DOF` the default value is: `0.25, 0.25, 0.25`

### `shadowPlane.smoothness=float:0.001…0.2…1.0`

Default value depends on shadowPlane.filter selection:

- Lightmap: 0.02
  Gauss, Linear, Invers: 0.2\
  Gauss2: 1.0\
  DOF: 0.05

affects the smoothness of the shadow plane boundary

Smaller values result in a sharper shadow boundary, whereas larger values result in a more blurred boundary. The option is ignored if the generated image does not contain a shadow plane.

### `shadowPlane.mirror=float:0.0…1.0`

**Default:** `0.0`

This option, if set to a non-zero value, causes the mirrored image of the rendered object to be displayed on the shadow plane.

### `shadowPlane.colorMode=enum:Color|GrayScale`

**Default:** [`Color`](/pCon/configuratorOnline/specs/api/basket/operations/getarticlerenderingsetup#ref-6b73191a0a4b)

This option controls whether the mirrored image on the shadow plane is displayed in color or gray scale.

### `shadowPlane.filter=enum:Gauss|Linear|Invers|Gauss2|Lightmap|DOF`

If not set, or set to an empty string, the shadow is based on the bounding box of the object. This is the default behavior. Otherwise, the shadow is based on the distance between the shadow plane and individual parts of the object. The specified filter selects the algorithm used to spread the shadow over the shadow plane. Available filters are:

`Gauss`  very smooth\
`Linear` moderately smooth\
`Invers` hard at the center, outwards too smooth\
`Gauss2` smooth, based on geometry distance (recommended)\
`Lightmap` To support OSAO-based shadows on the shadow plane\
`DOF`  Depth of Field algorithm

### `shadowPlane.border=float:-1.0…1.0`

**Default:** `-1.0`

affects the size of the shadow plane

If the value is zero then the shadow is about as large as the object. Values less than zero result in smaller shadows, values larger than zero in larger shadows.

This option is ignored if the `shadowPlane.filter` option is set.

### `shadowPlane.mapSize=int`

Specifies the size of the texture used for the shadow.

Attention: This parameter has a significant effect on rendering performance!

The default value is computed depending on the image size and the selected shadow plane filter. If `Gauss2` or Lightmap is selected as the shadow plane filter, the default shadow plane map size is equal to the sum of image width and height divided by two. Otherwise, it is equal to the sum of image width and height first divided by two and then divided by eight (not necessarily the same as division by 16 due to the use of integer arithmetic). The minimum default map size is 1.

The default value for filter modes other than `Gauss2` is much smaller because rendering times grow excessively for values greater than 256, and furthermore other than with `Gauss2`, reasonable results are achieved with smaller map sizes.

The shadow plane map size has been limited to a maximum of 4096 in case of shadow plane filter mode `Gauss2` and 512 for all other filter modes, including no filter. Greater values result in excessive rendering times, especially in case of filter modes other than `Gauss2`.

In case of shadow plane filter mode `DOF` the default value is computed based on *clamp((width + height) / 2, 1, 4096)*[^2]

This option is ignored if the `shadowPlane.filter` option is not set.

### `shadowPlane.maxHeight=float`

Specifies the maximum height of objects considered for the generation of shadows. The effect on the shadow is maximal at 0.001 height (i.e. if the object is immediately above the shadow plane), and diminishes up the the specified height.

The default value is the height of the bounding box (relative to the xz-plane) of the object being rendered.

In case of shadow plane filter mode `DOF` the default value is `0.25`.

This option is ignored if the `shadowPlane.filter` option is not set.

### `shadowPlane.radius=float`

For shadow plane filter `Lightmap` the default value is computed depending on the height of the bounding box.

### `shadowPlane.intensity=float:0.0…0.3…1.0`

In case of linear color workflow[^3] the default value is 1.0.

### `shadowPlane.samples=int:1…20…256`

For lightmap-based shadow planes.

### `projectionMode=enum:Perspective|Orthographic`

**Default:** `Perspective`

sets the projection mode used to render the image

The default projection mode depends on whether or not the `scale` option is used. Orthographic projection is used for true to scale images, perspective projection otherwise. In fact, specifying a projection mode other than `Orthographic` is not allowed for true to scale images.

### `zoom=float:1.0…30.0…89.0`

**Default:** `30.0`

### `alpha=float:-180.0…-15.0…360.0`

**Default:** `-15.0`

### `beta=float:-90.0…20.0…90.0`

**Default:** `20.0`

The zoom (angle of view), alpha (longitude of view point) and beta (latitude of view point) parameters are used to compute both the angle of view and the position (view point) of the camera.

The center of the bounding box is always used as the reference point. The view point is located at the axis starting a the reference point and pointing into the direction specified by the `alpha` and `beta` angles.

If orthographic projection is used, a possibly specified zoom is ignored.

If perspective projection is used, the distance between view point and reference point is computed such that, given the specified zoom, the article plus some small margin is always visible. Furthermore, if the latitude of the view point has not been explicitly specified, the height of the view point is limited to about 1.7 meter.

If the `scale` option is not used, the default values for zoom, longitude and latitude are 30.0, -15.0 and 20.0.

If the `scale` option is used, the `zoom` option must not be specified. Furthermore, both the longitude and latitude must be multiples of 90.0 degree. The default value for the longitude is zero degree, and the default value for the latitude depends on the longitude. If the longitude is zero, the default latitude is 90.0 degree. Otherwise, it is zero degree.

In any case, if the latitude is ±90.0 degree, then the longitude must be zero.

### `scale=float:1.0…10,000.0`

The `scale` option may be used to generate a true to scale image. The value of the `scale` option species the number of pixels per meter.

Use of the `scale` option is mutually exclusive with the `width`, `height` and `zoom` options and restricts the set of available values for the `projectionMode`, `alpha` and `beta` options.

Image generation fails if the chosen scale results in an image width and/or height greater than 2048 pixels (including the margin).

### `margin=int:0…5…512`

**Default:** `5`

The `margin` option may be used together with the `scale` option to add a margin of the specified number of pixels around the image. Thus the width and height of the generated image is computed as the minimum required width and height to fit the image representation of the article plus twice the margin.

If the `scale` option is not used, the `margin` option must not be used either.

### `enableShaders=boolean:true`

**Default:** `true`

This option, if set to `true`, enables the use of GL shading language.

If the `renderMode` option is set to a value other than `Textures`, shaders are always disabled, regardless of the value of the `enableShaders` option.

Starting with EAIWS 3.1, the default value for this option is `true` as the use of shaders does not only result in images of better quality, but also reduces rendering time.

### `mcp.obx=boolean:true`

**Default:** `true`

Format: MCP

If true, the MCP container contains the file articles.obx with commercial information about the objects.

### `mcp.comIDs=boolean:false`

**Default:** `false`

Format: MCP

If `mcp.obx` is false, but this option is `true`, the objects.xml file contained in the MCP container uses the `<comID>` element to store the commercial ID (basket item ID) of each object. This may violate the MCP specification, but may be used to optimize cases where the client needs to associate parts of the image with basket positions, but does not need the articles.obx file (because it obtains the    information contained in this file in some other way).

If `mcp.obx` is true, the value of this option is ignored.

A client that receives an MCP URL from the `getGeneratedImage` operation can now always access all member files of an MCP file by stripping of the '.eimg' suffix from the MCP URL and appending a slash followed by the member file name.

### `ars=boolean:false`

Enables the use of Article-specific Rendering Setups (ARS)

### `ars.camera=boolean:true`

Enable/disable use of the camera setup specified in the ARS database.

### `ars.lighting=boolean:true`

Enable/disable use of the lighting specified in the ARS database.

### `ars.view=<view-id> (default: empty)`

Specify alternative view ID that can be used to select a non-default ARS setup (if provided by the database).

### `osao=boolean:false`

Obsolete! Option is still accepted, but otherwise ignored for image generation..

Enables Object Space Ambient Occlusion (has no effect on OSAO-based shadows on the shadow plane, as described below)

### `osao.radius=float:0.002…10.0…`

Obsolete! Option is still accepted, but otherwise ignored for image generation.

### `osao.intensity=float:0.0…0.3…1.0`

Obsolete! Option is still accepted, but otherwise ignored for image generation..

### `osao.mapSize=int:32…1024…4096`

Controls the total size (width and height in texels) of the lightmap computed for all surfaces of the article.

### `osao.smoothness=float:0.001…0.02…1.0`

### `osao.samples=int:1…20…256`

### `viewId=<view-id>`

If the option is present then its value must be either the NIL-UUID (possibly represented by an empty string) or the ID of a basket view used by the current session.

If the option is not present, or if its value is the NIL-UUID, then the item ID is interpreted as the ID of a basket item. Otherwise the item ID is interpreted as the ID of a view item of the specified view, and the image is generated for the basket item referenced by this view item, or, in case of merged article view items, for one basket item randomly chosen from the set of referenced basket items. An error occurs if the referenced basket item is not an article item.

Furthermore, if the `viewId` option specifies a valid view ID, the `tag` option is not present, has an empty value, or has value `default`, and the `hideSubArticles` option is not present, the option `hideSubArticles=false` is added if the view uses merge mode `Compact` or the type of the referenced article is `PartialPlanning`[^4].

The `getGeneratedImage` operation returns an empty string if the product data does not support automatic generation of article images, if the Online Configurator has been configured not to generate article images, if the necessary license feature could not be leased during start-up of the Online Configurator, or if the process of generating the article image failed for whatever reason. Otherwise, the operation returns an URL referencing the generated image. The URL remains valid until the session is explicitly closed by the [`closeSession`](/pCon/configuratorOnline/specs/api/session/operations/closesession) operation of the session service, or is automatically closed after a configurable time of inactivity (§[Timeout for Sessions](/pCon/configuratorOnline/specs/guide/configuration/server-start-up-file/timeout-for-sessions#ref-7ba729350dca)).

If a true to scale image has been generated (by use of the `scale` option), the returned URL contains a query part specifying the width and height of the generated image as well as the local bounding box of the article’s 3D geometry. The query part may or may not be stripped from the URL before the URL is used to fetch the image.

The query part is separated from the URL path by a question mark (`?`) and consists of a sequence of key-value pairs separated by ampersands (`&`). Each key-value pair consists of a key, an equals sign (`=`), and integral or floating point number. The keys `width` and `height` are used to return the dimension of the generated image in pixels. Their values are positive integers. The keys `xmin`, `ymin`, `zmin`, `xmax`, `ymax` and `zmax` are used to return the dimension of the local bounding box of the article’s 3D geometry within a right-handed coordinate system with a horizontal xy-plane. Their values are floating point numbers in computerized scientific notation or decimal format, depending on the precision and the value in meter after rounding.

The `getGeneratedImage` operation may be called multiple times for the same article item with different options. For each set of options a new image will be generated. Successive calls of `getGeneratedImage` for the same article item with an identical set of options will not regenerate the image unless there was an intervening call of the [`setPropertyValue`](/pCon/configuratorOnline/specs/api/basket/operations/setpropertyvalue) operation.

If operation `getGeneratedImage` is invoked with the NIL-UUID (or an empty string) as item ID, and the `viewId` option is not present or specifies the NIL-UUID (or an empty string), the specified options are stored for the current session and later used whenever an article image needs to be generated on demand.

A [`BasketServiceFault`](/pCon/configuratorOnline/specs/api/basket/faults/basketservicefault) is returned if any of the following conditions occurs:

- The `sessionId` parameter is not a valid string representation of an UUID or does not represent an open session.

- The `itemId` parameter does not represent an UUID.

- The `itemId` parameter does not identify an article item.

- One of the specified options has an invalid value[^5] [^6].

- If used to set default image generation options and the specified format is neither JPEG nor PNG.

**Change behaviour of operations** getGeneratedImage and [getExportedGeometry](/pCon/configuratorOnline/specs/api/basket/operations/getexportedgeometry#ref-0862014d3e84) of basket service:

If the operation is invoked to get an image or geometry for a set-article item, and the geometry compositor fails to obtain the geometry for at least one set-article part, the operation terminates with a [BasketServiceFault](/pCon/configuratorOnline/specs/api/basket/faults/basketservicefault#ref-d5adb74faa1b) instead of returning an empty string (as was the case before). The field \`partCompositionFailures\` of the fault contains information about **all** parts that should have a geometry, but failed to provide one.

Mechanism that allows HTTP client to control Content-Disposition response header for GET requests referencing files in the session cache ([Client control of the header Content-Disposition for files in the session cache).](/pCon/configuratorOnline/specs/api/basket/image-generation/client-control-of-the-header-content-disposition-for-files-in-the-session-cache#ref-ff2a1af8f0eb)

[^1]: In case of a composite article, images stored for aggregates and partial plannings containing the changed article are reset too.

[^2]: *Width* and *height* are the width and height of the generated image.

[^3]: Server startup file option `egr.eai.gf.color_space=LinearRGB` or option `renderMode=PBR` of operation `getGeneratedImage`.

[^4]: In other words, if operation `getGeneratedImage` is used to generate the default article image through a view item then, unless explicitly specified otherwise, the value of option `hideSubArticles` is chosen as appropriate for the image to be displayed in the order list.

[^5]: The current implementation does not enforce the allowed value ranges specified for the `alpha` and `beta` option values. They should nevertheless be honored by a client of the basket service as this is not guaranteed for future versions of the Online Configurator.

[^6]: If not explicitly mentioned otherwise, the value of an option must always be valid according to the specification, even if the option is ignored, or the operation will fail.
