Cesium3DTileFeature

new Cesium.Cesium3DTileFeature()
engine/Source/Scene/Cesium3DTileFeature.js 43

A feature of a Cesium3DTileset.

Provides access to a feature's properties stored in the tile's batch table, as well as the ability to show/hide a feature and change its highlight color via Cesium3DTileFeature#show and Cesium3DTileFeature#color, respectively.

Modifications to a Cesium3DTileFeature object have the lifetime of the tile's content. If the tile's content is unloaded, e.g., due to it going out of view and needing to free space in the cache for visible tiles, listen to the Cesium3DTileset#tileUnload event to save any modifications. Also listen to the Cesium3DTileset#tileVisible event to reapply any modifications.

Do not construct this directly. Access it through Cesium3DTileContent#getFeature or picking using Scene#pick.

Example:
// On mouse over, display all the properties for a feature in the console log.
handler.setInputAction(function(movement) {
    const feature = scene.pick(movement.endPosition);
    if (feature instanceof Cesium.Cesium3DTileFeature) {
        const propertyIds = feature.getPropertyIds();
        const length = propertyIds.length;
        for (let i = 0; i < length; ++i) {
            const propertyId = propertyIds[i];
            console.log(`{propertyId}: ${feature.getProperty(propertyId)}`);
        }
    }
}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);

Members

color : Color
engine/Source/Scene/Cesium3DTileFeature.js 84

Gets or sets the highlight color multiplied with the feature's color. When this is white, the feature's color is not changed. This is set for all features when a style's color is evaluated.
Default Value: Color.WHITE

readonly featureId : number
engine/Source/Scene/Cesium3DTileFeature.js 312

Get the feature ID associated with this feature. For 3D Tiles 1.0, the batch ID is returned. For EXT_mesh_features, this is the feature ID from the selected feature ID set.
Experimental

This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.

polylinePositions : Float64Array
engine/Source/Scene/Cesium3DTileFeature.js 243

Gets a typed array containing the ECEF positions of the polyline. Returns undefined if Cesium3DTileset#vectorKeepDecodedPositions is false or the feature is not a polyline in a vector tile.
Experimental

This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.

readonly primitive : Cesium3DTileset
engine/Source/Scene/Cesium3DTileFeature.js 294

All objects returned by Scene#pick have a primitive property. This returns the tileset containing the feature.

show : boolean
engine/Source/Scene/Cesium3DTileFeature.js 64

Gets or sets if the feature will be shown. This is set for all features when a style's show is evaluated.
Default Value: true

readonly tileset : Cesium3DTileset
engine/Source/Scene/Cesium3DTileFeature.js 278

Gets the tileset containing the feature.

translation : Cartesian4
engine/Source/Scene/Cesium3DTileFeature.js 214

获取或设置该 feature 的顶点坐标偏移值。其中 x、y、z 分量定义偏移方向，w 分量定义偏移距离，且 w 分量最小值为 0。

提示：glTF 2.0 规范定义顶点坐标为 Y 轴朝上。

注意：如果 glTF 内的节点矩阵会将顶点坐标从 Y-up 转换为 Z-up， 则需要设置 Cesium3DTileset#swapYZAxes 为 true 以确保瓦片包围盒的计算正确。

Default Value: Cartesian4.UNIT_X
Example:
var expanding = false;

// 按 feature 的 names 属性进行偏移
var translationByNames = {
  F_01: [0, 0, 1, 10], // 沿  Z 轴方向偏移 10 米
  F_02: [0, 0, 1, 20],
  F_03: [0, 0, 1, 30],
  F_04: [0, 0, 1, 40],
  F_05: [0, 0, 1, 50],
  F_06: [0, 0, 1, 60],
  F_07: [0, 0, 1, 70],
  F_08: [0, 0, 1, 80],
  F_09: [0, 0, 1, 90],
  LH_43: [0, 0, 1, 0], // 沿  Z 轴方向偏移  0 米
  B_01: [0, 0, -1, 10],// 沿 -Z 轴方向偏移 10 米
  B_02: [0, 0, -1, 20],
  B_03: [0, 0, -1, 30],
};

// 每一帧的偏移距离
var distancePerFrame = 2;

var tileset = new Cesium.Cesium3DTileset({
  url: 'path/to/tileset.json'
});

tileset.tileVisible.addEventListener(function(tile) {

  updateTileTranslation({
    tile,
    expanding: expanding
  });

});

function updateFeaturesTranslation(options) {
  var content = options.content;
  var expanding = Cesium.defaultValue(options.expanding, false);

  var featuresLength = content.featuresLength;

  for (var i = 0; i < featuresLength; i++) {
    var feature = content.getFeature(i);
    var featureNames = feature.getProperty('names');
    var oldTranslation = feature.translation;

    if (expanding) {
      var translation = translationByNames[featureNames];
      if (translation && oldTranslation.w < translation[3]) {
        var distance = Math.min(translation[3], oldTranslation.w + distancePerFrame);
        feature.translation = new Cesium.Cartesian4(translation[0], translation[1], translation[2], distance);
      }
    } else if (oldTranslation.w > 0.0) {
      var distance = oldTranslation.w - distancePerFrame;
      feature.translation = new Cesium.Cartesian4(oldTranslation.x, oldTranslation.y, oldTranslation.z, distance);
    }

  }

}

function updateTileTranslation(options) {

  var tile = options.tile;
  var expanding = options.expanding;

  var content = tile.content;

  if (!content) {
    return;
  }

  if (content instanceof Cesium.Model3DTileContent) {

    updateFeaturesTranslation({
      content,
      expanding
    });

  } else if (content instanceof Cesium.Composite3DTileContent) {

    var contents = content.innerContents;

    for (var index = 0; index < contents.length; index++) {
      var innerContent = contents[index];

      updateFeaturesTranslation({
        content: innerContent,
        expanding
      });

    }
  }

}

Methods

static Cesium.Cesium3DTileFeature.getPropertyInherited(content, batchId, name) → *
engine/Source/Scene/Cesium3DTileFeature.js 412

Returns a copy of the feature's property with the given name, examining all the metadata from 3D Tiles 1.0 formats, the EXT_structural_metadata and legacy EXT_feature_metadata glTF extensions, and the metadata present either in the tileset JSON (3D Tiles 1.1) or in the 3DTILES_metadata 3D Tiles extension. Metadata is checked against name from most specific to most general and the first match is returned. Metadata is checked in this order:
  1. Batch table (structural metadata) property by semantic
  2. Batch table (structural metadata) property by property ID
  3. Content metadata property by semantic
  4. Content metadata property by property
  5. Tile metadata property by semantic
  6. Tile metadata property by property ID
  7. Subtree metadata property by semantic
  8. Subtree metadata property by property ID
  9. Group metadata property by semantic
  10. Group metadata property by property ID
  11. Tileset metadata property by semantic
  12. Tileset metadata property by property ID
  13. Otherwise, return undefined

For 3D Tiles Next details, see the 3DTILES_metadata Extension for 3D Tiles, as well as the EXT_structural_metadata Extension for glTF. For the legacy glTF extension, see EXT_feature_metadata Extension

Name Type Description
content Cesium3DTileContent The content for accessing the metadata
batchId number The batch ID (or feature ID) of the feature to get a property for
name string The semantic or property ID of the feature. Semantics are checked before property IDs in each granularity of metadata.
Returns:
The value of the property or undefined if the feature does not have this property.
Experimental

This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.

getProperty(name) → *
engine/Source/Scene/Cesium3DTileFeature.js 372

Returns a copy of the value of the feature's property with the given name. This includes properties from this feature's class and inherited classes when using a batch table hierarchy.
Name Type Description
name string The case-sensitive name of the property.
Returns:
The value of the property or undefined if the feature does not have this property.
Example:
// Display all the properties for a feature in the console log.
const propertyIds = feature.getPropertyIds();
const length = propertyIds.length;
for (let i = 0; i < length; ++i) {
    const propertyId = propertyIds[i];
    console.log(`{propertyId}: ${feature.getProperty(propertyId)}`);
}
See:

getPropertyIds(results) → Array.<string>
engine/Source/Scene/Cesium3DTileFeature.js 350

Returns an array of property IDs for the feature. This includes properties from this feature's class and inherited classes when using a batch table hierarchy.
Name Type Description
results Array.<string> optional An array into which to store the results.
Returns:
The IDs of the feature's properties.
See:

hasProperty(name) → boolean
engine/Source/Scene/Cesium3DTileFeature.js 337

Returns whether the feature contains this property. This includes properties from this feature's class and inherited classes when using a batch table hierarchy.
Name Type Description
name string The case-sensitive name of the property.
Returns:
Whether the feature contains this property.
See:

setProperty(name, value)
engine/Source/Scene/Cesium3DTileFeature.js 535

Sets the value of the feature's property with the given name.

If a property with the given name doesn't exist, it is created.

Name Type Description
name string The case-sensitive name of the property.
value * The value of the property that will be copied.
Throws:
  • DeveloperError : Inherited batch table hierarchy property is read only.
Examples:
const height = feature.getProperty('Height'); // e.g., the height of a building
const name = 'clicked';
if (feature.getProperty(name)) {
    console.log('already clicked');
} else {
    feature.setProperty(name, true);
    console.log('first click');
}
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.
packages/engine
packages/widgets