---
title: "setImages"
slug: "api/basket/operations/setimages"
sidebar:
  order: 529
---

<a id="ref-24800cae75c8"></a>
<a id="ref-2bea48b1db4a"></a>

## Synopsis

```text
void setImages(SessionId sessionId, ImageInfo[] imageInfos,
    SetImagesOptions? options) throws BasketServiceFault;
```

See also: [`SessionId`](/pCon/configuratorOnline/specs/api/session/types/sessionid), [`SetImagesOptions`](/pCon/configuratorOnline/specs/api/basket/types/setimagesoptions)

The setImages operation imports images into the project and stores them either as tagged images on basket items (item images), or, when tag is empty, as configuration-specific images for OFML article items (article images).

Images to import must be specified by HTTP(S) URLs known to the server and accessible to the session. These are usually client uploads, including archive members, but may also be image URLs returned by the server for this session, including catalog images. The generated field determines whether an image is imported as generated or ordinary. Imported resources are referenced by gen or imp URIs, respectively.

[ImageInfo](/pCon/configuratorOnline/specs/api/basket/types/imageinfo).url may instead contain a gen or imp URI referencing an image already imported into the project. In that case import is skipped and attributes must not be specified, because they are taken from the existing resource.

Ordinary imported images store only width, height and suffix. The client need not specify them because the server can derive them from the image file. Explicit width and height values are not verified against the file. If missing, they are obtained from the file. If suffix is missing, it is extracted from the URL file name. In either case it is converted to lower case. If a signature check identifies the format, suffix and format must agree: JPEG accepts jpg or jpeg; TIFF accepts tif or tiff; PNG accepts png; GIF accepts gif; BMP accepts bmp.

Generated images also store attributes describing the article configuration, camera and rendering setup. P-BK Offline uses the camera and rendering setup to regenerate images after property changes; EAIWS uses the camera setup. The server obtains configuration attributes from the article, but the client must provide the other required attributes because they cannot be derived from the image file. See [Imported File Attributes](/pCon/configuratorOnline/specs/api/basket/types/imported-file-attributes) for the supported attributes and required combinations.

<a id="ref-8ea401bbbf0a"></a>
<a id="ref-3b4df18c9e2f"></a>

## Argument Validation

Stage 1 validates all [ImageInfo](/pCon/configuratorOnline/specs/api/basket/types/imageinfo) instances before importing any images. A failure terminates the operation with [BasketServiceFault](/pCon/configuratorOnline/specs/api/basket/faults/basketservicefault). The following checks and preparations are performed.

The tag, if non-empty, must be a valid Unicode identifier. itemId is mandatory and must identify an existing basket item, even though it is optional in the XSD. No two entries may have the same combination of item ID and tag.

The url must parse as an absolute URI with a scheme. For gen, generated must be true if specified and defaults to true. For imp, generated must be false if specified and defaults to false. For HTTP(S), generated defaults to true when tag is empty and false otherwise.

An empty tag requires an OFML article item and an effective generated value of true.

attributes must be a possibly empty list of key=value pairs. Keys must be valid ANSI C identifiers. Duplicate keys are discarded, with the last value prevailing. No attributes may be supplied for gen or imp URIs.

For a gen URI used with an OFML article item, the stored resource attributes describing the article configuration must match that item’s configuration.

For HTTP(S) images requiring import, an effective generated value of true requires an OFML article item. The attribute list is updated with configuration attributes taken from that item, whether the image is an article image or a tagged item image.

One image import job is created per distinct combination of URL, attribute list and import type (generated or ordinary). Entries with the same combination share one import.

<a id="ref-6714c0463cfe"></a>
<a id="ref-878625082244"></a>

## Image Import and Assignment

Stage 2 converts each import job’s HTTP(S) URL to a path. The operation fails if the URL does not reference an existing file, or if deleteAfterImport=true and the session is not allowed to delete that file. Normally only files uploaded by a client of the current session may be deleted.

Stage 3 prepares each import by calling ISession.prepareGeneratedImageImport(Path, Map) or ISession.prepareFileImport(Path, Map). Preparation checks suffix, reads the file signature to identify its type and computes its MD5 digest. The operation fails if the identified file format does not match the suffix. Generated image imports additionally require JPEG or PNG, and add the format attribute. The digest is later used to create the imported resource URI.

Unsupported attributes are discarded. Supported values are checked for syntax and range. If the format is known and width and/or height is missing, the operation fails if only one was specified or if dimensions cannot be read from the image file. Generated image import additionally checks required attributes and camera consistency. EAIWS must be able to regenerate the image after property changes: refPtState must be 2 (center), and viewPtState must be 3 (default polar coordinates) or 4 (polar coordinates with manually specified azimuth and elevation).

Stage 4 performs the actual imports. Client errors are not expected at this stage, but the operation may still fail, most likely due to file cache I/O errors. Importing a resource whose URI already exists in the project has no effect. For historical reasons, imp URIs depend solely on the MD5 digest of file content. Incorrect width or height stored during the initial import therefore cannot be corrected by importing the same file again.

Stage 5, if resetExisting=true (default false), resets all tagged item images on each basket item referenced by imageInfos. Article images and images stored in user-defined columns are not affected.

Stage 6 assigns each image URI, either supplied directly or obtained from import. A non-empty tag stores an item image on the specified basket item. An empty tag stores an article image in the basket and propagates it to all OFML article items with the same configuration or, in certain cases, the same geometry checksum.

Basket-level article image storage also allows subsequently inserted articles with that configuration, and articles acquiring it through property changes, to reuse the same image. This persists as long as the project has not meanwhile been saved and loaded with all previously existing articles using that configuration deleted.

Stage 7, if deleteAfterImport=true (default false), deletes all imported image files. A deletion failure writes a server log message but does not fail the operation.
