On this page
Properties
Accessors
Methods
applycalculateCenterFromCameraLngLatAltcalculateFogMatrixclearNearFarZOverrideclonegetBoundsgetCameraAltitudegetCameraFrustumgetCameraLngLatgetCameraPointgetCameraQueryGeometrygetCircleRadiusCorrectiongetClippingPlanegetCoveringTilesDetailsProvidergetFastPathSimpleProjectionMatrixgetMatrixForModelgetMaxBoundsgetPitchedTextCorrectiongetPixelScalegetProjectionDatagetProjectionDataForCustomLayergetRayDirectionFromPixelgetVisibleUnwrappedCoordinatesinterpolatePaddingisLocationOccludedisPaddingEqualisPointOnMapSurfacelngLatToCameraDepthlocationToScreenPointmaxPitchScaleFactoroverrideNearFarZpopulateCacheprojectTileCoordinatesrecalculateZoomAndCenterresizescreenPointToLocationscreenPointToMercatorCoordinatesetBearingsetCentersetConstrainOverridesetElevationsetFovsetLocationAtPointsetMaxBoundssetMaxPitchsetMaxZoomsetMinElevationForCurrentTilesetMinPitchsetMinZoomsetPaddingsetPitchsetRenderWorldCopiessetRollsetTransitionStatesetZoomtransformLightDirection

Interface ITransform

interface ITransform {
    applyConstrain: TransformConstrainFunction;
    defaultConstrain: TransformConstrainFunction;
    get autoCalculateNearFarZ(): boolean;
    get bearing(): number;
    get bearingInRadians(): number;
    get cameraPosition(): vec3;
    get cameraToCenterDistance(): number;
    get center(): LngLat;
    get centerOffset(): Point;
    get centerPoint(): Point;
    get clipSpaceToPixelsMatrix(): mat4;
    get constrainOverride(): TransformConstrainFunction;
    get elevation(): number;
    get farZ(): number;
    get fov(): number;
    get fovInRadians(): number;
    get height(): number;
    get inverseProjectionMatrix(): mat4;
    get latRange(): [number, number];
    get lngRange(): [number, number];
    get maxPitch(): number;
    get maxZoom(): number;
    get minElevationForCurrentTile(): number;
    get minPitch(): number;
    get minZoom(): number;
    get modelViewProjectionMatrix(): mat4;
    get nearZ(): number;
    get padding(): PaddingOptions;
    get pitch(): number;
    get pitchInRadians(): number;
    get pixelsPerMeter(): number;
    get pixelsToClipSpaceMatrix(): mat4;
    get pixelsToGLUnits(): [number, number];
    get projectionMatrix(): mat4;
    get renderWorldCopies(): boolean;
    get roll(): number;
    get rollInRadians(): number;
    get rotationMatrix(): mat2;
    get scale(): number;
    get size(): Point;
    get tileSize(): number;
    get tileZoom(): number;
    get unmodified(): boolean;
    get width(): number;
    get worldSize(): number;
    get zoom(): number;
    apply(that: IReadonlyTransform, constrain: boolean): void;
    calculateCenterFromCameraLngLatAlt(
        lngLat: LngLatLike,
        alt: number,
        bearing?: number,
        pitch?: number,
    ): { center: LngLat; elevation: number; zoom: number };
    calculateFogMatrix(unwrappedTileID: UnwrappedTileID): mat4;
    clearNearFarZOverride(): void;
    clone(): ITransform;
    getBounds(): LngLatBounds;
    getCameraAltitude(): number;
    getCameraFrustum(): Frustum;
    getCameraLngLat(): LngLat;
    getCameraPoint(): Point;
    getCameraQueryGeometry(queryGeometry: Point[]): Point[];
    getCircleRadiusCorrection(): number;
    getClippingPlane(): vec4 | null;
    getCoveringTilesDetailsProvider(): CoveringTilesDetailsProvider;
    getFastPathSimpleProjectionMatrix(
        tileID: OverscaledTileID,
    ): mat4 | undefined;
    getMatrixForModel(location: LngLatLike, altitude?: number): mat4;
    getMaxBounds(): LngLatBounds | null;
    getPitchedTextCorrection(
        textAnchorX: number,
        textAnchorY: number,
        tileID: UnwrappedTileID,
    ): number;
    getPixelScale(): number;
    getProjectionData(params: ProjectionDataParams): ProjectionData;
    getProjectionDataForCustomLayer(applyGlobeMatrix: boolean): ProjectionData;
    getRayDirectionFromPixel(p: Point): vec3;
    getVisibleUnwrappedCoordinates(tileID: CanonicalTileID): UnwrappedTileID[];
    interpolatePadding(
        start: PaddingOptions,
        target: PaddingOptions,
        t: number,
    ): void;
    isLocationOccluded(lngLat: LngLat): boolean;
    isPaddingEqual(padding: PaddingOptions): boolean;
    isPointOnMapSurface(p: Point, terrain?: Terrain): boolean;
    lngLatToCameraDepth(lngLat: LngLat, elevation: number): number;
    locationToScreenPoint(lnglat: LngLat, terrain?: Terrain): Point;
    maxPitchScaleFactor(): number;
    overrideNearFarZ(nearZ: number, farZ: number): void;
    populateCache(coords: OverscaledTileID[]): void;
    projectTileCoordinates(
        x: number,
        y: number,
        unwrappedTileID: UnwrappedTileID,
        getElevation: (x: number, y: number) => number,
    ): PointProjection;
    recalculateZoomAndCenter(terrain?: Terrain): void;
    resize(width: number, height: number, constrainTransform: boolean): void;
    screenPointToLocation(p: Point, terrain?: Terrain): LngLat;
    screenPointToMercatorCoordinate(
        p: Point,
        terrain?: Terrain,
    ): MercatorCoordinate;
    setBearing(bearing: number): void;
    setCenter(center: LngLat): void;
    setConstrainOverride(constrain?: TransformConstrainFunction | null): void;
    setElevation(elevation: number): void;
    setFov(fov: number): void;
    setLocationAtPoint(lnglat: LngLat, point: Point): void;
    setMaxBounds(bounds?: LngLatBounds | null): void;
    setMaxPitch(pitch: number): void;
    setMaxZoom(zoom: number): void;
    setMinElevationForCurrentTile(elevation: number): void;
    setMinPitch(pitch: number): void;
    setMinZoom(zoom: number): void;
    setPadding(padding: PaddingOptions): void;
    setPitch(pitch: number): void;
    setRenderWorldCopies(renderWorldCopies: boolean): void;
    setRoll(roll: number): void;
    setTransitionState(value: number, error: number): void;
    setZoom(zoom: number): void;
    transformLightDirection(dir: vec3): vec3;
}

Hierarchy (View Summary)

Index

Properties

applyConstrain defaultConstrain

Accessors

autoCalculateNearFarZ bearing bearingInRadians cameraPosition cameraToCenterDistance center centerOffset centerPoint clipSpaceToPixelsMatrix constrainOverride elevation farZ fov fovInRadians height inverseProjectionMatrix latRange lngRange maxPitch maxZoom minElevationForCurrentTile minPitch minZoom modelViewProjectionMatrix nearZ padding pitch pitchInRadians pixelsPerMeter pixelsToClipSpaceMatrix pixelsToGLUnits projectionMatrix renderWorldCopies roll rollInRadians rotationMatrix scale size tileSize tileZoom unmodified width worldSize zoom

Methods

apply calculateCenterFromCameraLngLatAlt calculateFogMatrix clearNearFarZOverride clone getBounds getCameraAltitude getCameraFrustum getCameraLngLat getCameraPoint getCameraQueryGeometry getCircleRadiusCorrection getClippingPlane getCoveringTilesDetailsProvider getFastPathSimpleProjectionMatrix getMatrixForModel getMaxBounds getPitchedTextCorrection getPixelScale getProjectionData getProjectionDataForCustomLayer getRayDirectionFromPixel getVisibleUnwrappedCoordinates interpolatePadding isLocationOccluded isPaddingEqual isPointOnMapSurface lngLatToCameraDepth locationToScreenPoint maxPitchScaleFactor overrideNearFarZ populateCache projectTileCoordinates recalculateZoomAndCenter resize screenPointToLocation screenPointToMercatorCoordinate setBearing setCenter setConstrainOverride setElevation setFov setLocationAtPoint setMaxBounds setMaxPitch setMaxZoom setMinElevationForCurrentTile setMinPitch setMinZoom setPadding setPitch setRenderWorldCopies setRoll setTransitionState setZoom transformLightDirection

Properties

applyConstrain: TransformConstrainFunction

Constrain the center lngLat and zoom to ensure that longitude and latitude bounds are respected and regions beyond the map bounds are not displayed.

defaultConstrain: TransformConstrainFunction

The tranform's default callback that ensures that longitude and latitude bounds are respected by the viewport.

Accessors

  • get autoCalculateNearFarZ(): boolean

    Returns boolean

  • get bearing(): number

    Bearing in degrees.

    Returns number

  • get bearingInRadians(): number

    Returns number

  • get cameraPosition(): vec3

    Returns vec3

    Returns the camera's position transformed to be in the same space as 3D features under this transform's projection. Mostly used for globe + fill-extrusion.

  • get cameraToCenterDistance(): number

    Distance from camera origin to view plane, in pixels. Calculated using vertical fov and viewport height. Center is considered to be in the middle of the viewport.

    Returns number

  • get center(): LngLat

    Returns LngLat

  • get centerOffset(): Point

    Returns Point

  • get centerPoint(): Point

    The center of the screen in pixels with the top-left corner being (0,0) and +y axis pointing downwards. This accounts for padding.

    Returns Point

  • get clipSpaceToPixelsMatrix(): mat4

    Returns mat4

  • get elevation(): number

    Returns number

  • get farZ(): number

    Returns number

  • get fov(): number

    Vertical field of view in degrees.

    Returns number

  • get fovInRadians(): number

    Returns number

  • get height(): number

    Gets the transform's height in pixels. Use ITransform.resize to set the transform's size.

    Returns number

  • get inverseProjectionMatrix(): mat4

    Inverse of matrix from camera space to clip space.

    Returns mat4

  • get latRange(): [number, number]

    Returns [number, number]

  • get lngRange(): [number, number]

    Returns [number, number]

  • get maxPitch(): number

    Returns number

  • get maxZoom(): number

    Returns number

  • get minElevationForCurrentTile(): number

    Returns number

  • get minPitch(): number

    Returns number

  • get minZoom(): number

    Returns number

  • get modelViewProjectionMatrix(): mat4

    Returns mat4

  • get nearZ(): number

    Returns number

  • get pitch(): number

    Pitch in degrees.

    Returns number

  • get pitchInRadians(): number

    Returns number

  • get pixelsPerMeter(): number

    Returns number

  • get pixelsToClipSpaceMatrix(): mat4

    Returns mat4

  • get pixelsToGLUnits(): [number, number]

    Returns [number, number]

  • get projectionMatrix(): mat4

    Returns mat4

  • get renderWorldCopies(): boolean

    Returns boolean

  • get roll(): number

    Roll in degrees.

    Returns number

  • get rollInRadians(): number

    Returns number

  • get rotationMatrix(): mat2

    Returns mat2

  • get scale(): number

    How many times "larger" the world is compared to zoom 0. Usually computed as pow(2, zoom). Relevant mostly for mercator projection.

    Returns number

  • get size(): Point

    Gets the transform's width and height in pixels (viewport size). Use resize to set the transform's size.

    Returns Point

  • get tileSize(): number

    Returns number

  • get tileZoom(): number

    Returns number

  • get unmodified(): boolean

    Returns boolean

  • get width(): number

    Gets the transform's width in pixels. Use ITransform.resize to set the transform's size.

    Returns number

  • get worldSize(): number

    How many units the current world has. Computed by multiplying worldSize by tileSize. Relevant mostly for mercator projection.

    Returns number

  • get zoom(): number

    Returns number

Methods

  • Applies a transform to the current transform.

    Parameters

    • that: IReadonlyTransform

      The transform to apply to the current transform.

    • constrain: boolean

      Whether to constrain the transform's center and zoom and recompute internal matrices once applied.

    Returns void

  • Given the camera position (lng, lat, alt), calculate the center point and zoom level

    Parameters

    • lngLat: LngLatLike

      lng, lat of the camera

    • alt: number

      altitude of the camera above sea level, in meters

    • Optionalbearing: number

      bearing of the camera, in degrees

    • Optionalpitch: number

      pitch angle of the camera, in degrees

    Returns { center: LngLat; elevation: number; zoom: number }

  • Returns LngLatBounds

    Returns a LngLatBounds object describing the map's geographical bounds.

    Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.

  • The camera looks at the map from a 3D (lng, lat, altitude) location. Let's use cameraLocation as the name for the location under the camera and on the surface of the earth (lng, lat, 0). cameraPoint is the projected position of the cameraLocation.

    This point is useful to us because only fill-extrusions that are between cameraPoint and the query point on the surface of the earth can extend and intersect the query.

    When the map is not pitched the cameraPoint is equivalent to the center of the map because the camera is right above the center of the map.

    Returns Point

  • When the map is pitched, some of the 3D features that intersect a query will not intersect the query at the surface of the earth. Instead the feature may be closer and only intersect the query because it extrudes into the air.

    Parameters

    • queryGeometry: Point[]

      For point queries, the line from the query point to the "camera point", for other geometries, the envelope of the query geometry and the "camera point"

    Returns Point[]

    a geometry that includes all of the original query as well as all possible ares of the screen where the base of a visible extrusion could be.

  • Returns number

    Allows the projection to adjust the radius of circle-pitch-alignment: 'map' circles and heatmap kernels based on the map's latitude. Circle radius and heatmap kernel radius is multiplied by this value.

  • Returns vec4 | null

    Return the clipping plane, behind which nothing should be rendered. If the camera frustum is sufficient to describe the render geometry (additional clipping is not required), this may be null.

  • Returns a matrix that will place, rotate and scale a model to display at the given location and altitude while also being projected by the custom layer matrix. This function is intended to be called from custom layers.

    Parameters

    • location: LngLatLike

      Location of the model.

    • Optionalaltitude: number

      Altitude of the model. May be undefined.

    Returns mat4

  • Parameters

    • textAnchorX: number

      Text anchor position inside the tile, X axis.

    • textAnchorY: number

      Text anchor position inside the tile, Y axis.

    • tileID: UnwrappedTileID

      The tile coordinates.

    Returns number

    Allows the projection to adjust the scale of text-pitch-alignment: 'map' symbols's collision boxes based on the map's center and the text anchor. Only affects the collision boxes (and click areas), scaling of the rendered text is mostly handled in shaders.

  • Parameters

    Returns boolean

    Returns whether the supplied location is occluded in this projection. For example during globe rendering a location on the backfacing side of the globe is occluded.

  • Parameters

    • p: Point

      The point's coordinates.

    • Optionalterrain: Terrain

      Optional terrain.

    Returns boolean

    Returns whether the specified screen point lies on the map. May return false if, for example, the point is above the map's horizon, or if doesn't lie on the planet's surface if globe is enabled.

  • Return the distance to the camera in clip space from a LngLat. This can be compared to the value from the depth buffer (terrain.depthAtPoint) to determine whether a point is occluded.

    Parameters

    • lngLat: LngLat

      the point

    • elevation: number

      the point's elevation

    Returns number

    depth value in clip space (between 0 and 1)

  • Sets the overriding values to use for near and far Z instead of what the transform would normally compute. If set to undefined, the transform will compute its ideal values. Calling this will set autoCalculateNearFarZ to false.

    Parameters

    • nearZ: number
    • farZ: number

    Returns void

  • Parameters

    Returns void

    Called before rendering to allow the transform implementation to precompute data needed to render the given tiles. Used in mercator transform to precompute tile matrices (posMatrix).

  • This method works in combination with freezeElevation activated. freezeElevation is enabled during map-panning because during this the camera should sit in constant height. After panning finished, call this method to recalculate the zoom level and center point for the current camera-height in current terrain.

    Parameters

    • Optionalterrain: Terrain

      the terrain

    Returns void

  • Sets the transform's width and height and recomputes internal matrices.

    Parameters

    • width: number
    • height: number
    • constrainTransform: boolean

    Returns void

  • Sets the transform's bearing, in degrees. Recomputes internal matrices if needed.

    Parameters

    • bearing: number

    Returns void

  • Sets the transform's center. Automatically constrains the transform's center and zoom and recomputes internal matrices if needed.

    Parameters

    Returns void

  • Sets the transform's vertical field of view, in degrees. Recomputes internal matrices if needed.

    Parameters

    • fov: number

    Returns void

  • Set's the transform's center so that the given point on screen is at the given world coordinates.

    Parameters

    • lnglat: LngLat

      Desired world coordinates of the point.

    • point: Point

      The screen point that should lie at the given coordinates.

    Returns void

  • Sets the transform's maximal allowed pitch, in degrees. Automatically constrains the transform's pitch to the new range and recomputes internal matrices if needed.

    Parameters

    • pitch: number

    Returns void

  • Sets the transform's maximal allowed zoom level. Automatically constrains the transform's zoom to the new range and recomputes internal matrices if needed.

    Parameters

    • zoom: number

    Returns void

  • Sets the transform's minimal allowed pitch, in degrees. Automatically constrains the transform's pitch to the new range and recomputes internal matrices if needed.

    Parameters

    • pitch: number

    Returns void

  • Sets the transform's minimal allowed zoom level. Automatically constrains the transform's zoom to the new range and recomputes internal matrices if needed.

    Parameters

    • zoom: number

    Returns void

  • Sets the transform's pitch, in degrees. Recomputes internal matrices if needed.

    Parameters

    • pitch: number

    Returns void

  • Sets the transform's roll, in degrees. Recomputes internal matrices if needed.

    Parameters

    • roll: number

    Returns void

  • Parameters

    • value: number

      The transition state value.

    • error: number

      The error value.

    Returns void

    Sets the transform's transition state from one projection to another.

  • Sets the transform's zoom. Automatically constrains the transform's center and zoom and recomputes internal matrices if needed.

    Parameters

    • zoom: number

    Returns void

  • Parameters

    • dir: vec3

      The light direction.

    Returns vec3

    A new vector with the transformed light direction.

    Returns light direction transformed to be in the same space as 3D features under this projection. Mostly used for globe + fill-extrusion.

Was this helpful?
SDK JS
Reference
ITransform