Skip to content
pCon.configurator onlineDocumentation
Esc
↑↓navigate↵open⌘Jpreview
On this page

getExportedGeometry

Synopsis

URL getExportedGeometry(SessionId sessionId,
    BItemId itemId,
    string[]  options
)
throws BasketServiceFault;

See also: URL, SessionId, BItemId, BasketServiceFault

The getExportedGeometry operation is used to export the 3D geometry of 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=3DS"). The following options are available (specified default values are listed below the option syntax):

format=enum:3DS|DWG|GFX|SKP|FBX|OBJ|DAE|IGXC|GFJ|GLTF|USD|PEC|L3D|GLDF

Default: 3DS

The format option specifies the format that will be used by the geometry export. Currently supported formats are 3DS (the default), DWG, GFX (for EOX-GFX1), FBX and SKP2.

format=GLTF

In addition to the standard options hideSubArticles, layerControl, centerXZ, compression, and scale the following options are supported:

ascii=<boolean> - If false (default value), the export produces a single GLB file. Otherwise the export produces a ZIP file containing a file named geometry.gltf and zero or more additional files referenced with relative paths by the GLTF file.

To get an URL for individual files, the client may replace the .zip suffix of the returned URL with a slash and the name/path of the file as used in the ZIP file.

Option compression=true may not be used with ascii=false. compression=false is ignored if used with ascii=false.

texTrans=<boolean> - If set to true, exports texture coordinates with transformation. This way at most one set of UV coordinates is written, which most viewers are able to cope with better.

This export requires license feature egr.eai.server.export.gltf.

format=USD

In addition to the standard options hideSubArticles, layerControl, centerXZ, compression, and scale the following options are supported:

ascii=<boolean> - If false (default value), the export produces a single USDZ file. Otherwise the export produces a ZIP file containing a file named geometry.usda and zero or more additional files referenced with relative paths by the USDA file.

To get an URL for individual files, the client may replace the .zip suffix of the returned URL with a slash and the name/path of the file as used in the ZIP file.

Option compression=true may not be used with ascii=false. compression=false is ignored if used with ascii=false.

texTrans=<boolean> - If set to true, exports texture coordinates with transformation. Files produced with texTrans=true can currently not be processed by ArKit (Apple).

This export requires license feature egr.eai.server.export.usd.

centerXZ=boolean:false

Default: false

Being either true or false, to most geometry exports (all except CCL and EGMS). If set to true (default value is false), the geometry is exported so its bounding box is centred around the Y (vertical) axis. Y coordinates are not affected.

dwgSymbol=boolean:false

Default: false

Formats: GFJ

Default: false

Being either true or false, to GFJ geometry export. If true (default value is false), the GFJ file references a single 2D DWG file containing the 2D geometry of the exported object.

hideSubArticles=boolean:false

Default: false

Formats: all

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

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.

serverBase=url

Formats: GFX, IGXC,GFJ

The serverBase option, if specified, should be a valid (HTTP) URL. It is used by exports that produce files which contain URLs to other resources, like images or geometries. The relative path of the image or geometry resource (like OFML/data/…) is resolved3 against the server base. The resulting URL is then written to the exported file.

The default value for serverBase is http://hostname:port/, where hostname and port are derived from the header of the HTTP request carrying the body of the getExportedGeometry operation.

geometryExtensions=extension-list:.geo,.3ds,.dxf,.dwg,.obj,.glb,.gltf

imageExtensions=extension-list:.rgb,.tga,.jpg,.bmp

Formats: GFX, IGXC, GFJ

These options are used to specify the set of geometry and image file formats the client is willing to deal with as well as the search order. The values of these options must be formatted the same way as the value of the egr.eai.http.ofml_extensions start-up file entry (§OFML File Extensions), except that there must be no leading PLUS SIGN. If one of these options contains an extension that is not part of the default set of extensions served by the OFML HTTP server, then the afore mentioned start-up file entry should be used to configure the OFML HTTP server to serve files with this extension, or HTTP requests for these files will result in a 404 (Not Found) HTTP error.

In case of the IGXC and GFJ export, the default value for option geometryExtensions is .obj. The default list of image extensions for GFJ export consists of .jpg and .png, in that order.

If the IGXC/GFJ export needs a geometry, it first attempts to find a geometry file within the OFML data, using the specified geometry extension list to select and prioritize geometry formats. If no such file can be found, the export generates the required geometry. If the first extension from the extension list is .glb or .gltf, the export will generate GLB or GLTF geometries, respectively. Otherwise, it will generate OBJ geometries.

hierarchyMode=enum:Hierarchy|MatrixStack|MaterialStack|Flat|Path|Children

Default: MatrixStack

Formats: GFX, FBX (only supports Hierarchy|Flat)

Flat

No hierarchy, i.e. all (geometric) primitives are on the same level.

Hierarchy

Writes the OFML object hierarchy, but materials and transforms are still assigned to primitives (leave nodes) only.

MatrixStack

Writes the OFML object hierarchy, transforms are assigned to top objects (inner nodes), if possible. Materials are assigned to primitives (leave nodes).

MaterialStack

Like MatrixStack, but materials are assigned to top objects too.

Formats: IGXC

Path (default)

If set to Path, the geometry objects are exported as an array of JSON objects. Each object has a key named “Path” and a value of type string. The string can be used to rebuild the object hierarchy.

Children

If set to Children, the geometry objects are exported as a tree of JSON objects. Each inner node object of the tree has a key named “Children”, whose value is an array of child objects.

obx.enabled=boolean:false

Default: false

Formats: GFX

If set to true, the export produces a ZIP file that contains the GFX file as geometry.gfx. <eoxObject/> elements that represent the root of the hierarchy of geometries for an article have the attribute comInfo. The value of the comInfo attribute is a relative URI that is to be resolved against the URI for geometry.gfx. The scheme specific part of the resulting URI identifies an OBX file, and the fragment (remaining characters after the number sign (#)) the article item within the OBX file through its item identifier.

At present, the OBX file is always named 1.obx, but future versions of the Online Configurator may use another name, or even multiple files. Therefore the name of the OBX file must always be taken from the value of the comInfo attribute.

obx.encoding=string:UTF-8

Default: UTF-8

Formats: GFX

This option allows the specification of the character set to be used when the OBX file is written.

scale=float:1.0

Default: 1.0

Formats: 3DS, DWG, SKP, FBX, OBJ, DAE

Scale the output geometry by the given factor.

duplicateFaces=boolean:false

Default: false

Formats: 3DS, FBX, DAE

For each face (triangle), write another face with the same vertices but reverse orientation. Useful, if you want to feed the output to applications, which do not handle oriented faces correctly.

empty=boolean:true

Default: true

Formats: 3DS

Generate one face for empty meshes. Useful, if output is to be fed to applications which can not handle empty meshes (this includes 3DStudio(Max) itself, at least for some versions).

use3DProxies=boolean:true

Default: true

Formats: DWG

If true, DWGs from the data packages (“Proxy DWGs”) are directly included in the output. If false, imported DWGs are tessellated to polygon meshes.

This option should be set to false if output is to be fed to applications which do not handle ACIS primitives. It should be set to true if output is to be fed to AutoCAD, since AutoCAD R17 and above have problems rendering polygon meshes.

textures=boolean

Formats: 3DS, DWG, SKP, FBX, OBJ, DAE, L3D, GLDF

Default:
3DS, SKP, FBX, OBJ, DAE, L3D, GLDF: false

DWG: true

If materials=false or textureToColor=true or acadColorIndex=true the default value is always false.

This option controls whether the export just exports the geometry (value false), or exports both the geometry and texture images (value true).

For 3DS, OBJ and DAE if the value of this option is false, the returned URL references a single geometry file. Otherwise, the returned URL references a ZIP file. One entry of the ZIP file is named geometry.<format>. If the geometry references texture images, these texture images are also packed into the ZIP file, using the same names as done by the geometry.

If the returned URL references a ZIP file, but the client is unable or unwilling to deal with the ZIP file4, the client is still able to fetch the individual geometry and image files. To do so, it must strip the .zip suffix from the returned URL and append /geometry.<format>. This URL can then be used to fetch the geometry. The client can then analyse the geometry to get the texture image file names, and, for each image file name, replace geometry.<format> with the name of the texture image to form an URL that can be used to fetch the texture image.

If option textureToColor is true textures are not exported, no matter what the value of the textures option.

materials=boolean

Formats: DWG, SKP, FBX, OBJ, DAE, IGXC, L3D, GLDF

Default:
DWG, SKP, FBX, DAE, L3D, GLDF: true

OBJ, IGXC: false

If textures=true or textureToColor=true and not acadColorIndex=true the default value is always true.

If acadColorIndex=true and not textures=true the default value is always false.If true, export materials, if false export just geometries.

For OBJ a value of true for this option requires the OBJ export to return a ZIP file.

ofmlMaterials=boolean:false

Default: false

Formats: IGXC

Write materials in OMATS format.

textureToColor=boolean:false

Default: false

Formats: DWG, SKP, FBX, DAE

If this option is true, average texture colors instead of diffuse colors are exported. Furthermore, textures are not exported, no matter what the value of the textures option.

acadColorIndex=boolean:false

Default: false

Formats: DWG

If this option is true, materials will get AutoCAD colors.

staticMaterials=boolean:false

Default: false

Formats: IGXC

Enable export of static materials only.

shortMaterialNames=boolean:false

Default: false

Formats: FBX

layers=boolean:false

Default: false

Formats: IGXC

Write layer information

no2D=boolean

Formats: DWG, SKP, FBX, DAE, GFJ

Default:
SKP, FBX, DAE, GFJ: true

DWG, PEC: false

If true, do not export 2D geometries, i.e. export 3D only. In case of PEC this option is always false, so PEC always contains a 2D geometry. It is not possible to turn of the 2D symbol. This is also the case for the dwg file contained in the PEC export (Option dwg.enabled=true).

no3D=boolean:false

Default: false

Formats: DWG

If true, do not export 3D geometries, i.e. export 2D only.

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.

layerRules

This option is used to summarize the layers inside the DWGs. The rules which apply for summarizing can be defined in an xml file, which is saved in the directory ./etc/elayers/. By default EAIWS has one layer rule file available under ./etc/elayers/color.xml.The value of this option must be a relative path name to the elayer directory (./etc/elayers).

Formats: DWG

r17=boolean:true

Default: true

Formats: DWG

If true, export in AutoCAD R17 format, if false, use AutoCAD R16.

dxf=boolean:false

Default: false

Formats: DWG

If true, export in DXF instead of DWG format.

resolution=enum:Default|Low

Default: Default

Formats: SKP, FBX, DAE

With value Low, the exports export low-resolution geometries, if available in the OFML data.

Low-resolution geometries are stored in geometry files starting with an underscore. Thus, if the name of the standard geometry file is ‘foo.geo’, the name of the low-resolution geometry file is ‘_foo.geo’. If no low-resolution geometry file is found, the standard geometry is used instead.

This mechanism works for all supported geometry formats as long as the geometry is accessed through a qualified name (i.e. ::manu::prog::geo_name).

edges=boolean:false

Formats: DAE

Activate edges for DAE export.

annotation=boolean:false

Default: false

Formats: DWG

If true, export additional geometries to support snapping in pCon.xcad and pCon.planner 6.

compression=<level>

Formats: all exports that return a ZIP file (GFX, 3DS, OBJ, DAE, PEC, L3D, GLDF)

If specified, <level> must be either an integer between zero and nine, both inclusive (with 0 disabling compression and 9 resulting in maximal compression, the default value is 6) or a boolean value true or false (default: false).

This option is recognised by all geometry exports that may return a ZIP file. These exports return a ZIP file if some information produced by the export cannot be stored as part of the geometry file (textures in case of 3DS, textures and materials in case of OBJ, OBX in case of GFX). In case of PEC it controls the compression level used for non-texture entries of the PEC file. Even with compression enabled, entries in GLDF and L3D files are not compressed if their content is known to be already compressed.

If these exports return no ZIP file, the compression option has no effect. Otherwise, if the value of this option is false, or if the name of the ZIP file entry ends with .jpg, .jpeg or .png, the ZIP file entry is stored without compression. Otherwise, the ZIP file entry is compressed.

Currently, compression level 4 is used as a test with an OBJ file with one (rather small) texture image showed this as the greatest level with a marginal benefit (relative reduction in file size divided by the relative increase in computation time) greater than one.

If the OBJ export returns the URL of a ZIP file, looking like http://<host>/<path>/<filename>.zip, the files contained in the ZIP file can also be accessed using an URL where <filename>.zip is replaced by <filename>/<element-name>, with <element-name> being geometry.obj, geometry.mtl, or <texture-name>.jpg.

compactJSON=boolean:false

Default: false

Formats: IGXC

Omit indentations and newlines.

jsonArrays=boolean:false

Default: false

Formats: IGXC

Write colors and vectors as JSON arrays

crc128=boolean:false

Default: false

Formats: IGXC

Use CRC128 checksums for geometries. This also enables the use of a global geometry cache for geometries generated by the export.

basketIds=boolean:false

Default: false

Formats: IGXC

If true, geometry objects that correspond to a basket article item have a key named “BasketId”. The value is a 36 character long string representing the item ID of the basket article item formatted as an UUID consisting of only hex digits and minus signs.

Right now this option is ignored if the exported item is not a basket article (i.e. its BasketItemType is neither Article, Aggregate or PartialPlanning).

skpVersion=enum:SU3|SU4|SU5|SU6|SU7|SU8|SU2013|SU2014|SU2015|SU2016

Controls the version of the exported SKP file. If no version is specified, or the specified version is not understood by the FAPI converter, the most recent version supported by the SKP SDK will be used.

revit=boolean:false

Default: false

Formats: GFX

If this option is true, the GFX export will pack the GFX file into a ZIP file (name geometry.gfx). Furthermore, if the export selects a DWG file as a part geometry, the DWG will be scaled as necessary and added to the ZIP file. The geometry references within the GFX file will contain relative URIs that must be resolved relative to the root of the ZIP file.

The option revit=true should probably be used together with option geometryExtensions=.dwg

A client may also modify the ZIP file URL as follows to download the GFX and DWG files:

  1. Strip the suffx (.zip) from the URL.

  2. Append a slash (‘/’) character.

  3. Append the (path) name of the file as used in the ZIP file.

Thus, if the ZIP file URL is

http://host/.../foo.zip

the URL of the GFX file would be

http://host/.../foo/geometry.gfx

The same can be done for the DWG files once their (path) names have been extracted from geometry.gfx.

edwg=boolean:false

Default: false

Formats: DWG

Right now, the EDWG export is supported for OFML articles (simple and composite) only (i.e. not for OCD articles or sets of OFML articles).

maxImageSize=integer

Format: GFJ, IGXC, PEC

It controls the maximum size (width/height) of texture images referenced by the GFJ/IGXC/PEC file. The option’s value must be a non-negative decimal, hexadecimal or octal integer less than 231. A value of zero disables the option. Values between zero and N are replaced with N (where N is some arbitrarily chosen small positive integer, currently 16). The default value is zero.

scaleFilter=enum: Legacy|Linear|BiCubic|Lanczos2

Format: PEC

Determines the scale filter to be used if a texture image needs to be rescaled.

omitPriceData=boolean:false

Default: false

Format: PEC

Controls whether price data should be omitted from document.obx and from OBX snippets embedded in document.dwg (if enabled).

preview.enabled=boolean:false

Default: false

Format: PEC

Controls whether a preview image should be generated and embedded within the PEC file. The following options are always accepted but ignored unless preview.enabled is true:

  • preview.width

  • preview.height

  • preview.resample

  • preview.quality

  • preview.ambient

  • preview.background

  • preview.renderMode

  • preview.enableShaders

  • preview.fadeBorder

  • preview.shadowPlane

  • preview.shadowPlane.border

  • preview.shadowPlane.color

  • preview.shadowPlane.smoothness

  • preview.shadowPlane.mirror

  • preview.shadowPlane.colorMode

  • preview.shadowPlane.mapSize

  • preview.shadowPlane.filter

  • preview.shadowPlane.maxHeight

  • preview.shadowPlane.radius

  • preview.shadowPlane.intensity

  • preview.shadowPlane.samples

  • preview.zoom

  • preview.alpha

  • preview.beta

  • preview.projectionMode

If preview.enabled is true, these options validated after all other options have been processed. Their allowed values are equal to those of the corresponding image export options with the preview. prefix removed (see basket service operation getGeneratedImage).

camera=<camera-specification>

Format: PEC

Determines the values stored in the <camera/> element of pec.xml.

The camera specification consists of four (perspective) or five (orthographic) fields separated by colon (:). The values of individual fields must be as follows:

  1. perspective or orthographic

  2. a three-element array representing the viewpoint

  3. a three-element array representing the viewing direction

  4. a three-element array representing the up-vector

  5. a single number representing half the visible size in y-direction

The vectors representing viewing direction and up-vector don’t need to be normalized, but must be non-zero.

Arrays start with a left square bracket ([), end with a right square bracket (]), and contain numbers separated by comma (,).

All numbers must adhere to the usual syntax for floating point numbers. Special numbers like NaN and Inf are not allowed.

Whitespace at the start and end of the camera specification, around field separators, and around numbers is ignored.

If no camera option is present, but preview.enabled is true, the camera specification is derived from the camera settings used to generate the preview image. Otherwise, no <camera/> element is written to pec.xml.

dwg.enabled=boolean

Format: PEC

Controls whether the generated PEC file contains an EDWG file (document.dwg)

The getExportedGeometry operation returns an empty string if the product data does not support export of geometries, if the Online Configurator has been configured not to export geometries of the selected format, if the license feature necessary for the selected format could not be leased during start-up of the Online Configurator, or if the process of exporting the geometry failed for whatever reason. Otherwise, the operation returns an URL referencing the exported geometry, or a ZIP file containing the geometry. 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).

The getExportedGeometry operation may be called multiple times for the same article item with different options. For each set of options a new geometry will be exported. If getExportedGeometry is called successively for the same article item with an identical set of options then the geometry will not be re-exported unless there was an intervening call of the setPropertyValue operation.

A 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.

  • If textures are enabled and materials are disabled.

  • If textures are enabled and texture-to-color are enabled.

  • If texture-to-color is enabled and materials are disabled unless acad-color-index is enabled.

  • If acad-color-index is enabled and either textures or materials is enabled.

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

  1. EOX-GFX is a format that does not include the actual geometries, but contains a list of geometries and materials as well as instructions on how to compose them to the final geometry. Furthermore, it may reference (and be delivered together with) an OBX file that contains commercial information for the exported article. ↩

  2. Only available on Microsoft Windows. ↩

  3. Note that the parsing of the serverBase option fails if the URI is relative or opaque, or has a query or fragment component. Furthermore, it automatically appends a slash to the path component if the path component does not already end with a slash. ↩

  4. The format of the ZIP file is kept quite simple. Particularly, it uses neither compression nor encryption. There are no extra fields, comments, or data descriptors, and the crc-32, compressed-size, and uncompressed-size fields of the local file headers are all valid. Thus it is possible to process the ZIP file in a single pass, as there is no need to read the central directory before the entries can be reliably extracted. ↩