IonAssetElementService

Queries the individual elements within a Cesium ion asset backed by a BIM/CAD Database model, using the ion REST API's Asset Elements endpoints. Element ids are typically obtained by picking a Cesium3DTileFeature and reading its element property. This object is normally not instantiated directly, use IonAssetElementService.fromAssetId.

new Cesium.IonAssetElementService(options)

Name Type Description
options object Object with the following properties:
Name Type Description
assetId number The ion asset id.
resource Resource The asset's ion API resource.
Example:
const elements = Cesium.IonAssetElementService.fromAssetId(123456);
const page = await elements.listElements({
  filter: { "IFC Attributes.name": { $like: "%Rebar%" } },
  top: 50,
});
console.log(`${page.items.length} of ${page.total} elements`);
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

See:

Extends

Members

The ion asset id this service operates on.

Methods

static Cesium.IonAssetElementService.fromAssetId(assetId, options) → IonAssetElementService

Creates an IonAssetElementService for the given ion asset.
Name Type Description
assetId number The ion id of an asset backed by a BIM/CAD Database model.
options object optional Object with the following properties:
Name Type Default Description
accessToken string Ion.defaultAccessToken optional The ion access token to use.
server string | Resource Ion.defaultServer optional The ion API server to use.
Returns:
A service bound to the asset.

static Cesium.IonAssetElementService.getBoundingSphere(element) → BoundingSphere|undefined

Computes a BoundingSphere enclosing an element from its location, suitable for framing the camera with Camera#flyToBoundingSphere or Viewer#zoomTo.
Name Type Description
element IonAssetElementService.Element An element returned by IonAssetElementService#getElement or IonAssetElementService#listElements.
Returns:
A bounding sphere for the element, or undefined if the element has no valid location.
Example:
const element = await elements.getElement(elementId);
const boundingSphere = Cesium.IonAssetElementService.getBoundingSphere(element);
if (Cesium.defined(boundingSphere)) {
  viewer.camera.flyToBoundingSphere(boundingSphere);
}

static Cesium.IonAssetElementService.getElementId(feature) → string|undefined

Reads the element id from a picked Cesium3DTileFeature. Rendered features carry the id of the element they belong to in their element property. The returned id can be passed directly to IonAssetElementService#getElement.
Name Type Description
feature Cesium3DTileFeature A feature picked from the asset's tileset.
Returns:
The element id as a decimal string, e.g. "3298534886898", or undefined if the feature has no element id.
Example:
const feature = viewer.scene.pick(movement.position);
const elementId = Cesium.IonAssetElementService.getElementId(feature);
if (Cesium.defined(elementId)) {
  const element = await elements.getElement(elementId);
}

async aggregate(options) → Promise.<{aggregations: Array.<IonAssetElementService.Aggregation>, total: number}>

Computes aggregate statistics (count, min, max, average, and sum) for one or more numeric properties across the elements of this asset, optionally filtered.
Name Type Description
options object Object with the following properties:
Name Type Description
propertyKeys Array.<string> The qualified property keys to aggregate. At least one is required.
filter object | string optional An element filter. See the Query parameters section of the Aggregate elements ion REST API documentation for the supported structure.
Returns:
A promise that resolves to the aggregate statistics. The promise rejects with a RequestErrorEvent if the request fails.
Throws:
  • DeveloperError : options.propertyKeys must be a non-empty array of strings.
Example:
try {
  const result = await elements.aggregate({
    propertyKeys: ["Volume Aspect.Net Volume"],
    filter: { "IFC Class Name": "ifcwall" },
  });
  console.log(result.aggregations, result.total);
} catch (error) {
  console.error(error.statusCode, error.response);
};
Retrieves metadata and location information for a single element. Use IonAssetElementService.getElementId to obtain the id from a picked Cesium3DTileFeature.
Name Type Description
elementId string The element id as a decimal string, e.g. "3298534886898".
Returns:
A promise that resolves to the requested element. The promise rejects with a RequestErrorEvent if the request fails or the element does not exist.

async getElementTreeChildren(options) → Promise.<{nodes: Array.<IonAssetElementService.ElementTreeNode>}>

Lists the children of a node in this asset's element tree, or the root nodes when no key is given.
Name Type Description
options object optional Object with the following properties:
Name Type Description
nodeKey string optional The opaque node key returned by the endpoint. Omit it to list root nodes.
Returns:
A promise that resolves to the child nodes. The promise rejects with a RequestErrorEvent if the request fails or a key for a node that does not exist is provided.
Throws:
Example:
try {
  const { nodes } = await elements.getElementTreeChildren();
  const { nodes: children } = await elements.getElementTreeChildren({
    nodeKey: nodes[0].key,
  });
  console.log(nodes);
} catch (error) {
  console.error(error.statusCode, error.response);
}

async getElementTreeParents(elementId) → Promise.<{path: Array.<IonAssetElementService.ElementTreePathEntry>}>

Retrieves the parents of an element in this asset's element tree, from the root down to the element, using ion's tree/parents endpoint.
Name Type Description
elementId string The element id as a decimal string, e.g. "3298534886898".
Returns:
A promise that resolves to the root-first path. The promise rejects with a RequestErrorEvent if the request fails or no path exists.
Throws:
Example:
try {
  const { path } = await elements.getElementTreeParents(elementId);
  console.log(path);
} catch (error) {
  console.error(error.statusCode, error.response);
}
Retrieves a page of elements for this asset, optionally filtered. Results are paginated with an opaque cursor. Request subsequent pages by passing the returned continuationToken as options.continuationToken until it is undefined.
Name Type Description
options object optional Object with the following properties:
Name Type Default Description
top number 100 optional The maximum number of elements to return per page.
continuationToken string optional A token returned from a previous call to retrieve the next page of results.
filter object | string optional An element filter. See the Query parameters section of the List elements ion REST API documentation for the supported structure.
Returns:
A promise that resolves to a page of elements. The promise rejects with a RequestErrorEvent if the request fails.
Throws:
Example:
const page = await elements.listElements({
  filter: {
    $or: [{ "IFC Class Name": "ifcwall" }, { "IFC Class Name": "ifccolumn" }],
  },
});

Type Definitions

Cesium.IonAssetElementService.Aggregation

Aggregate statistics for a single numeric property across a set of elements, as returned by IonAssetElementService#aggregate. Non-numeric properties come back with a count of 0, null for min, max, and avg, and a sum of 0.
Properties:
Name Type Description
propertyKey string The qualified property key these statistics describe.
count number The number of elements that had a numeric value for this property key.
min number | null The minimum value across the matched elements, or null when there are no numeric values.
max number | null The maximum value across the matched elements, or null when there are no numeric values.
avg number | null The mean value across the matched elements, or null when there are no numeric values.
sum number The sum of values across the matched elements.

Cesium.IonAssetElementService.Element

A single element of a Cesium ion asset, such as a wall or column in a BIM/CAD model.
Properties:
Name Type Attributes Description
id string The unique integer identifier of this element, as a decimal string, e.g. "3298534886898".
label string <optional>
The user-friendly label of this element, if any.
location IonAssetElementService.ElementLocation <optional>
The geographic location of this element, or undefined when the element has no location (e.g. conceptual elements, or assets with no geographic coordinate system).
properties Object.<string, IonAssetElementService.ElementProperty> <optional>
The properties of this element, keyed by property name. List results may omit properties; use IonAssetElementService#getElement to retrieve the element's details. Property names are kept verbatim, including any dotted namespaces (e.g. "Volume Aspect.Net Volume").

Cesium.IonAssetElementService.ElementLocation

The geographic location of an IonAssetElementService.Element, present only when the element is geolocated.

Cesium.IonAssetElementService.ElementPage

A page of results from IonAssetElementService#listElements.
Properties:
Name Type Attributes Description
items Array.<IonAssetElementService.Element> The elements on this page.
total number | null The total number of elements matching the query across all pages, or null when the total is unavailable.
continuationToken string <optional>
A token to pass as options.continuationToken to retrieve the next page, or undefined when there are no more results.

Cesium.IonAssetElementService.ElementProperty

A single property of an IonAssetElementService.Element.
Properties:
Name Type Attributes Description
value * The raw value of this property.
displayValue string <optional>
The human-readable, pre-formatted value, including any unit suffix (e.g. "0.6208 m³").
units string | null <optional>
The unit of value, or null or undefined when the property is unitless.

Cesium.IonAssetElementService.ElementTreeNode

A node in a Cesium ion asset's element tree, as returned by IonAssetElementService#getElementTreeChildren.
Properties:
Name Type Description
key string The opaque key of this node. Pass it as options.nodeKey to IonAssetElementService#getElementTreeChildren to list this node's children.
label string The user-friendly label of this node.
hasChildren boolean Whether this node has any children.
id string The integer instance id represented by this node, as a decimal string.
kind "subject" | "model" | "category" | "element" The kind of node.

Cesium.IonAssetElementService.ElementTreePathEntry

An entry in the root-first path returned by IonAssetElementService#getElementTreeParents. Entries include the target element as well as its ancestors.
Properties:
Name Type Description
kind "subject" | "model" | "category" | "element" The kind of path entry.
id string The integer instance id for this subject, model, category, or element, as a decimal string.
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.