ImageStyle | XYZ Maps Documentation

Interface for configuring the visual appearance of Images/Icons.

Hierarchy

ImageStyle

Index

Properties

Optional alignment

alignment: "map" | "viewport" | StyleValueFunction<string> | StyleZoomRange<string> | StyleExpression<string>

Alignment for styles of type "Circle". Possible values are: "map" and "viewport". "map" aligns to the plane of the map and "viewport" aligns to the plane of the viewport/screen. Default alignment for Text based on point geometries is "viewport" while "map" is the default for line geometries.

Optional altitude

Altitude of the Image center in meters.

Describes the vertical distance from the global ground plane (0m) to the Image.

Supported values:

false (default): place at 0m.

true: use the altitude (z) from the feature geometry if present, else 0. Not re-aligned to the rendered terrain.

  If the geometry altitude source differs from the TerrainTileLayer source/resolution, the Image can appear
  slightly above or below the visible terrain surface.

number: fixed absolute altitude in meters. Also not adjusted when terrain tiles load; may not perfectly sit
```
    on the terrain unless both use exactly the same elevation source, datum and resolution.
```

'terrain': sample (clamp to) the current terrain surface height. While the terrain tile is not yet loaded

       (or no terrain layer exists) the altitude is 0 and updates once data becomes available.

Notes:

Use 'terrain' to keep the Image visually seated on the rendered terrain.
Use a numeric value for a constant absolute elevation independent of terrain updates.
To position something N meters above terrain: use 'terrain' plus offsetZ (e.g. offsetZ: '5m').
Expect mismatches (floating / sinking) when using true or a fixed number with a different terrain data source.

defaultvalue: false
experimental

Optional anchor

Sets the anchor point for styles of type "Image" used with Line or Polygon geometry.

Possible values for Line geometry are "Coordinate" and "Line".

"Coordinate": the respective style is displayed at each coordinate of the polyline.
"Line": the respective style is displayed on the shape of the polyline when there is enough space. See checkLineSpace to disable the space check.

Possible values for Polygon geometry are "Center" and "Centroid".

"Center": the center of the bounding box of the polygon.
"Centroid": the geometric centroid of the polygon geometry.

defaultvalue: For Polygon geometry the default is "Center". For Line geometry the default is "Line".

Optional atlas

atlas: { height: number; width: number; x: number; y: number }

If specified, the Image provided by src is considered as an IconAtlas/TextureAtlas. The clipping region for the image must be defined by x, y, width and height. The maximum supported atlas size is 4096x4096.

Type declaration

height: number
width: number
x: number
y: number

Optional checkLineSpace

checkLineSpace: boolean | StyleValueFunction<boolean> | StyleZoomRange<boolean> | StyleExpression<boolean>

Enable or disable the space check for point styles on line geometries. If check checkLineSpace is enabled the respective style is only displayed if there is enough space on the line, otherwise it is not displayed.

defaultvalue: true

Optional collide

collide: boolean | StyleValueFunction<boolean> | StyleZoomRange<boolean> | StyleExpression<boolean>

Enable or disable collision detection. If the collision detection is enabled for multiple Styles within the same StyleGroup, the respective Styles are handled as a single Object ("CollisionGroup") where the combined bounding-box is determined automatically.

true: collision are allowed, Collision detection is disabled.
false: avoid collisions, Collision detection is enabled.

defaultvalue: false for "Text", true for all other.

Optional collisionGroup

collisionGroup: string | StyleValueFunction<string> | StyleZoomRange<string> | StyleExpression<string>

Enables collision detection and combines all styles of a StyleGroup with the same "CollisionGroup" into a single logical object for collision detection.

Optional height

height: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Height of the Image in pixels. The maximum supported height for "Image" is 64 pixels. The unit of width is defined in pixels. If the height is not explicitly defined, the value of the width is used as the height.

example

// define an Image that has a width of 32 and height of 64 pxiels
{
    zIndex: 0,
    type: "Image",
    src: "urlToImage.png",
    width: 32,
    height: 64
}

Optional offsetX

Offset the shape in pixels on x-axis. A positive value offsets to the right, a negative value to the left. The default unit is pixels.

example

// offset Image by 8px to the right.
{ type: "Image", zIndex: 0, src: '...', offsetX: 8}

Optional offsetY

offsetY: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Offset the shape in pixels on y-axis. A positive value offsetY offsets downwards, a negative value upwards. The default unit is pixels.

example

// offset Image by 8px to the bottom
{ type: "Image", zIndex: 0, src: '...', offsetY: 8}

Optional offsetZ

Offset the shape in pixels on z-axis. A positive value offsets up, a negative value down. The default unit is pixels.

example

// offset Image by 8px to the top.
{ type: "Image", zIndex: 0, src: '...', offsetZ: 8}

Optional opacity

opacity: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Defines the opacity of the style. The value must be between 0.0 (fully transparent) and 1.0 (fully opaque). It is valid for all style types.

defaultvalue: 1

Optional priority

priority: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

In case of label collision, Text with a higher priority (lower value) will be drawn before lower priorities (higher value). If the collision detection is enabled for multiple Styles within the same StyleGroup, the highest priority (lowest value) is used.

Optional repeat

repeat: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Minimum distance in pixels between repeated style-groups on line geometries. Applies per tile only.

defaultvalue: 256 (pixels)

Optional rotation

rotation: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Rotate the shape of the style to the angle in degrees.

Optional scaleByAltitude

scaleByAltitude: boolean | StyleValueFunction<boolean> | StyleZoomRange<boolean> | StyleExpression<boolean>

Scales the size of a style based on the feature's altitude. If it's enabled (true), features closer to the camera will be drawn larger than those farther away. When off (false), the size of the style is always the same size, regardless of its actual altitude, as if it were placed on the ground (altitude 0). This attribute applies to styles of type "Rect", "Image", "Text", "Circle", "Line", "Box", or "Sphere" whose size (width, {@link radius}, strokeWidth) that are using "map" alignment only. If the size attribute is defined in meters, scaleByAltitude is enabled by default, for pixels it is disabled.

defaultvalue: false (pixels), true (meters)
experimental

src

src: string | StyleValueFunction<string> | StyleZoomRange<string> | StyleExpression<string>

Specifies the URL of the image to render. It can be either absolute or relative path.

type

type: "Image"

Specifies the type of style to render.

width

width: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Width of the Image in pixels. The maximum supported width for "Image" is 64 pixels. The unit of width is defined in pixels.

example

// define an Image that has a width (and height) of 64 pxiels
{
    zIndex: 0,
    type: "Image",
    src: "urlToImage.png",
    width: 64
}

zIndex

zIndex: number | StyleValueFunction<number> | StyleZoomRange<number> | StyleExpression<number>

Indicates the drawing order within a layer. Styles with larger zIndex value are rendered above those with smaller values. The zIndex is defined relative to the "zLayer" property. If "zLayer" is defined all zIndex values are relative to the "zLayer" value.

Optional zLayer

zLayer: number | StyleValueFunction<number> | StyleExpression<number>

Indicates drawing order across multiple layers. Styles using zLayer with a high value are rendered on top of zLayers with a low value. If no zLayer is defined, it will fall back to the LayerStyle.zLayer or depend on the display layer order. The first (lowest) layer has a zLayer value of 1.

example: {...zLayer: 2, zIndex: 5} will be rendered on top of {...zLayer: 1, zIndex: 10}