ObjectSymbol3DLayer

require(["esri/symbols/ObjectSymbol3DLayer"], function(ObjectSymbol3DLayer) { /* code goes here */ });
Class: esri/symbols/ObjectSymbol3DLayer
Inheritance: ObjectSymbol3DLayer Symbol3DLayer Accessor
Since: ArcGIS API for JavaScript 4.0

ObjectSymbol3DLayer is used to render Point geometries using a volumetric 3D shape (e.g., a sphere or cylinder) with a PointSymbol3D in a SceneView. MapView does not support 3D symbols. Polygon features may also be rendered with ObjectSymbol3DLayers, but the object symbol layer must be contained in a PolygonSymbol3D, not a PointSymbol3D in this scenario.

The shape of the object is set in the resource property and the color of the object is set in the material property. The size of the object is always defined in meters. Size can be directly set in the height, width, and depth properties. Object color and size can also be data-driven by adding size and/or color visual variables to any Renderer that uses this symbol layer.

ObjectSymbol3DLayers must be added to the symbolLayers property of either PointSymbol3D or PolygonSymbol3D symbols. Multiple symbol layers may be used in a single symbol. The image below depicts a point FeatureLayer whose features are symbolized with a PointSymbol3D containing a cylinder-based ObjectSymbol3DLayer.

symbols-3d-objects

See Symbol3DLayer and Symbol3D to read more general information about 3D symbols, symbol layers and how they relate to one another.

Autocasting support

As of version 4.5 of the ArcGIS API for JavaScript, autocasting is universally supported for all renderers, symbols, and symbol layers in the API. So there is no need to include this module in the require() and define() module loaders of your application unless you intend to use the static method(s) of this module.

See also:
Examples:
// symbol using a cylinder as a resource
const symbol = {
  type: "point-3d",  // autocasts as new PointSymbol3D()
  symbolLayers: [{
    type: "object",  // autocasts as new ObjectSymbol3DLayer()
    width: 5,  // diameter of the object from east to west in meters
    height: 20,  // height of the object in meters
    depth: 15,  // diameter of the object from north to south in meters
    resource: { primitive: "cylinder" },
    material: { color: "red" }
  }]
};
// symbol using a glTF 3D model as a resource
const symbol = {
  type: "point-3d",  // autocasts as new PointSymbol3D()
  symbolLayers: [{
    type: "object",  // autocasts as new ObjectSymbol3DLayer()
    resource: {
      href: "../3d-assets/model.gltf"
    },
    height: 3,
    material: {
      color: "red"
    }
  }
};

Constructors

new ObjectSymbol3DLayer(properties)
Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
String

The positioning of the symbol relative to the geometry.

more details
more detailsObjectSymbol3DLayer
Object

Defines the anchor relative to the center of the symbol layer resource.

more details
more detailsObjectSymbol3DLayer
Boolean

Indicates whether the symbol layer geometry casts shadows in the scene.

more details
more detailsObjectSymbol3DLayer
String

The name of the class.

more details
more detailsAccessor
Number

The depth, or diameter from north to south, of the object in meters.

more details
more detailsObjectSymbol3DLayer
Number

The clockwise rotation of the symbol in the horizontal plane (i.e., around the z axis).

more details
more detailsObjectSymbol3DLayer
Number

The height of the object in meters.

more details
more detailsObjectSymbol3DLayer
Object

The material used to shade the object.

more details
more detailsObjectSymbol3DLayer
Object

The primitive shape (primitive) or external 3D model (href) used to visualize the points.

more details
more detailsObjectSymbol3DLayer
Number

The rotation of the symbol in the lateral vertical plane (i.e., around the y axis).

more details
more detailsObjectSymbol3DLayer
Number

The rotation of the symbol in the longitudinal vertical plane (i.e., around the x axis).

more details
more detailsObjectSymbol3DLayer
String

For ObjectSymbol3DLayer the type is always object.

more details
more detailsObjectSymbol3DLayer
Number

The width, or diameter from east to west, of the object in meters.

more details
more detailsObjectSymbol3DLayer

Property Details

anchor String

The positioning of the symbol relative to the geometry. The default behavior (origin) depends on the resource:

  • For sphere, cube and diamond primitives, the origin is at the center.
  • For cylinder, cone, inverted-cone and tetrahedron primitives, the origin is at the bottom.
  • For href resources, the origin coincides with the origin of the 3D model.

If anchor is set to relative, the anchor is defined by anchorPosition as a fraction of the symbol's bounding box.

Possible Values: center | top | bottom | origin | relative

Default Value:origin
anchorPosition Object
Since: ArcGIS API for JavaScript 4.10

Defines the anchor relative to the center of the symbol layer resource. It is specified as a ratio of the resource's bounding box dimensions. For example, a value of { x: 0, y: 0, z: 0 } designates the center, while a value of { x: -0.5, y: -0.5, z: -0.5 } places the symbol at the lower south-west corner of the symbol's bounding box.

This property only applies when anchor is set to relative.

Properties:

Value defining the position relative to the x axis of the bounding box.

Value defining the position relative to the y axis of the bounding box.

Value defining the position relative to the z axis of the bounding box.

Examples:
symbolLayer.anchor = "relative";
symbolLayer.anchorPosition = { x: 0, y: 0, z: -0.5 }; // equivalent to `anchor: "bottom"`
symbolLayer.anchor = "relative";
symbolLayer.anchorPosition = { x: 1.5, y: 1, z: 0 }; // the anchor can be placed outside of the symbol's bounding box
castShadows Boolean
Since: ArcGIS API for JavaScript 4.11

Indicates whether the symbol layer geometry casts shadows in the scene. Setting this property to false will disable shadows for the symbol layer even if direct shadows are enabled in SceneView.environment.

Default Value:true
Example:
// disables shadow casting
symbolLayer.castShadows = false;
declaredClass Stringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

depth Number

The depth, or diameter from north to south, of the object in meters. If undefined, the depth will be calculated to maintain the original proportions of the object.

Default Value:10
Example:
// depth of the symbol in meters
symbolLayer.depth = 5000;
heading Number

The clockwise rotation of the symbol in the horizontal plane (i.e., around the z axis). The rotation is specified in degrees and is relative to the y-axis.

If the symbol resource is aligned such that its forward facing side points in the direction of the y-axis (the y-axis always points North in WGS84 or WebMercator coordinates), its upwards facing side is pointing in the direction of the z-axis, and its right-hand side points in the direction of the x-axis (the x-axis always points East in WGS84 or WebMercator coordinates), then this angle corresponds to the heading of the symbol.

Example:
// heading of the symbol in degrees
symbolLayer.heading = 180;
height Number

The height of the object in meters. If undefined, the height will be calculated to maintain the original proportions of the object.

Default Value:10
Example:
// height of the symbol in meters
symbolLayer.height = 1000;

The material used to shade the object. This property defines the object's color.

Property:
color Color
optional
Default Value:white
Autocasts from Object|Number[]|String

The fill color of the object. If the object has textures, the textures will be multiplied with the color. This can be autocast with an array of rgb(a) values, named string, hex string or an hsl(a) string, an object with r, g, b, and a properties, or a Color object.

Examples:
// CSS color string
symbolLayer.material = {
  color: "dodgerblue"
};
// HEX string
symbolLayer.material = {
  color: "#33cc33";
}
// array of RGBA values
symbolLayer.material = {
  color: [51, 204, 51, 0.3];
}
// object with rgba properties
symbolLayer.material = {
  color: {
    r: 51,
    g: 51,
    b: 204,
    a: 0.7
  }
};
resource Object

The primitive shape (primitive) or external 3D model (href) used to visualize the points. If both properties are present, primitive takes precedence and href is ignored. When using the href property, external 3D models must be present in glTF format.

Properties:
primitive String
optional

Uses a built-in shape. See the table below for possible values.

ValueDescription
spheres3d-object-sphere
cylinders3d-object-cylinder
cubes3d-object-cube
cones3d-object-cone
inverted-cones3d-object-inverted-cone
diamonds3d-object-diamond
tetrahedrons3d-object-tetrahedron
href String
optional

The URL to the 3D model in glTF format. The URL should point to a glTF file (.gltf or .glb) which can reference additional binary (.bin) and image files (.jpg, .png). See the guide topic on Visualizing points with 3D symbols to learn how to use a custom 3D model.

Default Value:{ primitive: "sphere" }
See also:
roll Number
Since: ArcGIS API for JavaScript 4.4

The rotation of the symbol in the lateral vertical plane (i.e., around the y axis). The rotation is specified in degrees and is relative to the x-axis. At 0 degrees, the model is level. A positive value lifts the left part and lowers the right part of the model.

If the symbol resource is aligned such that its forward facing side points in the direction of the y-axis (the y-axis always points North in WGS84 or WebMercator coordinates), its upwards facing side is pointing in the direction of the z-axis, and its right-hand side points in the direction of the x-axis (the x-axis always points East in WGS84 or WebMercator coordinates), then this angle corresponds to the roll of the symbol.

Example:
// roll of the symbol in degrees
symbolLayer.roll = 90;
tilt Number
Since: ArcGIS API for JavaScript 4.4

The rotation of the symbol in the longitudinal vertical plane (i.e., around the x axis). The rotation is specified in degrees and is relative to the y-axis. At 0 degrees, the model is level. A positive value points lifts the front and lowers the back of the model.

If the symbol resource is aligned such that its forward facing side points in the direction of the y-axis (the y-axis always points North in WGS84 or WebMercator coordinates), its upwards facing side is pointing in the direction of the z-axis, and its right-hand side points in the direction of the x-axis (the x-axis always points East in WGS84 or WebMercator coordinates), then this angle corresponds to the tilt of the symbol.

Example:
// tilt of the symbol in degrees
symbolLayer.tilt = 45;
type Stringreadonly

For ObjectSymbol3DLayer the type is always object.

width Number

The width, or diameter from east to west, of the object in meters. If undefined, the width will be calculated to maintain the original proportions of the object.

Default Value:10
Example:
// width of the symbol in meters
symbolLayer.width = 5000;

Method Overview

NameReturn TypeSummaryClass
ObjectSymbol3DLayer

Creates a deep clone of the symbol layer.

more details
more detailsObjectSymbol3DLayer
*

Creates a new instance of this class and initializes it with values from a JSON object generated from a product in the ArcGIS platform.

more details
more detailsSymbol3DLayer
Object

Converts an instance of this class to its ArcGIS portal JSON representation.

more details
more detailsSymbol3DLayer

Method Details

Creates a deep clone of the symbol layer.

Returns:
TypeDescription
ObjectSymbol3DLayerA deep clone of the object that invoked this method.
Example:
// Creates a deep clone of the graphic's first symbol layer
var symLyr = graphic.symbol.symbolLayers.getItemAt(0).clone();
fromJSON(json){*}static

Creates a new instance of this class and initializes it with values from a JSON object generated from a product in the ArcGIS platform. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter:
json Object

A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns:
TypeDescription
*Returns a new instance of this class.
toJSON(){Object}inherited

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() topic in the Guide for more information.

Returns:
TypeDescription
ObjectThe ArcGIS portal JSON representation of an instance of this class.

API Reference search results

NameTypeModule
Loading...