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:
-
Strip the suffx (.zip) from the URL.
-
Append a slash (‘/’) character.
-
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:
-
perspectiveororthographic -
a three-element array representing the viewpoint
-
a three-element array representing the viewing direction
-
a three-element array representing the up-vector
-
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
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. -
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
-
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. ↩
-
Only available on Microsoft Windows. ↩
-
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. ↩
-
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. ↩