getGeneratedImage
Synopsis
URL getGeneratedImage(SessionId sessionId,
BItemId itemId,
string[] options)
throws BasketServiceFault;
See also: URL, SessionId, BItemId, BasketServiceFault
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:
"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 changed1. Furthermore, the saveSession (§saveSession) and loadSession (§loadSession) 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
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 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
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 workflow3 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 PartialPlanning4.
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 operation of the session service, or is automatically closed after a configurable time of inactivity (§Timeout for Sessions).
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 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 is returned if any of the following conditions occurs:
-
The
sessionIdparameter is not a valid string representation of an UUID or does not represent an open session. -
The
itemIdparameter does not represent an UUID. -
The
itemIdparameter does not identify an article item. -
If used to set default image generation options and the specified format is neither JPEG nor PNG.
Change behaviour of operations getGeneratedImage and getExportedGeometry 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 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).
Footnotes
-
In case of a composite article, images stored for aggregates and partial plannings containing the changed article are reset too. ↩
-
Width and height are the width and height of the generated image. ↩
-
Server startup file option
egr.eai.gf.color_space=LinearRGBor optionrenderMode=PBRof operationgetGeneratedImage. ↩ -
In other words, if operation
getGeneratedImageis used to generate the default article image through a view item then, unless explicitly specified otherwise, the value of optionhideSubArticlesis chosen as appropriate for the image to be displayed in the order list. ↩ -
The current implementation does not enforce the allowed value ranges specified for the
alphaandbetaoption 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. ↩ -
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. ↩