---
title: "CollisionIndex | JavaScript maps SDK"
description: "Documentation for MapTiler SDK"
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Class CollisionIndex

##### Index

### Constructors[](#constructors)

[constructor](#constructor)

### Properties[](#properties)

[grid](#grid) [gridBottomBoundary](#gridbottomboundary) [gridRightBoundary](#gridrightboundary) [ignoredGrid](#ignoredgrid) [perspectiveRatioCutoff](#perspectiveratiocutoff) [pitchFactor](#pitchfactor) [screenBottomBoundary](#screenbottomboundary) [screenRightBoundary](#screenrightboundary) [transform](#transform)

### Methods[](#methods)

[getPerspectiveRatio](#getperspectiveratio) [getViewportMatrix](#getviewportmatrix) [insertCollisionBox](#insertcollisionbox) [insertCollisionCircles](#insertcollisioncircles) [isInsideGrid](#isinsidegrid) [isOffscreen](#isoffscreen) [placeCollisionBox](#placecollisionbox) [placeCollisionCircles](#placecollisioncircles) [projectAndGetPerspectiveRatio](#projectandgetperspectiveratio) [projectPathToScreenSpace](#projectpathtoscreenspace) [queryRenderedSymbols](#queryrenderedsymbols)

## Constructors[](#constructors-1)

### constructor[](#constructor)

-   new CollisionIndex(  
        transform: [IReadonlyTransform](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.IReadonlyTransform/),  
        grid?: [GridIndex](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GridIndex/)<[FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)\>,  
        ignoredGrid?: [GridIndex](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GridIndex/)<[FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)\>,  
    ): CollisionIndex[](#constructorcollisionindex)
    
    #### Parameters
    
    -   transform: [IReadonlyTransform](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.IReadonlyTransform/)
    -   `Optional`grid: [GridIndex](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GridIndex/)<[FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)\>
    -   `Optional`ignoredGrid: [GridIndex](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GridIndex/)<[FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)\>
    
    #### Returns CollisionIndex
    

## Properties[](#properties-1)

### grid[](#grid)

grid: [GridIndex](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GridIndex/)<[FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)\>

### gridBottomBoundary[](#gridbottomboundary)

gridBottomBoundary: number

### gridRightBoundary[](#gridrightboundary)

gridRightBoundary: number

### ignoredGrid[](#ignoredgrid)

ignoredGrid: [GridIndex](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GridIndex/)<[FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)\>

### perspectiveRatioCutoff[](#perspectiveratiocutoff)

perspectiveRatioCutoff: number

### pitchFactor[](#pitchfactor)

pitchFactor: number

### screenBottomBoundary[](#screenbottomboundary)

screenBottomBoundary: number

### screenRightBoundary[](#screenrightboundary)

screenRightBoundary: number

### transform[](#transform)

transform: [IReadonlyTransform](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.IReadonlyTransform/)

## Methods[](#methods-1)

### getPerspectiveRatio[](#getperspectiveratio)

-   getPerspectiveRatio(  
        x: number,  
        y: number,  
        unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/),  
        getElevation?: (x: number, y: number) \=> number,  
    ): number[](#getperspectiveratio-1)
    
    #### Parameters
    
    -   x: number
    -   y: number
    -   unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/)
    -   `Optional`getElevation: (x: number, y: number) \=> number
    
    #### Returns number
    

### getViewportMatrix[](#getviewportmatrix)

-   getViewportMatrix(): [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/)[](#getviewportmatrix-1)
    
    #### Returns [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/)
    

### insertCollisionBox[](#insertcollisionbox)

-   insertCollisionBox(  
        collisionBox: number\[\],  
        overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/),  
        ignorePlacement: boolean,  
        bucketInstanceId: number,  
        featureIndex: number,  
        collisionGroupID: number,  
    ): void[](#insertcollisionbox-1)
    
    #### Parameters
    
    -   collisionBox: number\[\]
    -   overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/)
    -   ignorePlacement: boolean
    -   bucketInstanceId: number
    -   featureIndex: number
    -   collisionGroupID: number
    
    #### Returns void
    

### insertCollisionCircles[](#insertcollisioncircles)

-   insertCollisionCircles(  
        collisionCircles: number\[\],  
        overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/),  
        ignorePlacement: boolean,  
        bucketInstanceId: number,  
        featureIndex: number,  
        collisionGroupID: number,  
    ): void[](#insertcollisioncircles-1)
    
    #### Parameters
    
    -   collisionCircles: number\[\]
    -   overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/)
    -   ignorePlacement: boolean
    -   bucketInstanceId: number
    -   featureIndex: number
    -   collisionGroupID: number
    
    #### Returns void
    

### isInsideGrid[](#isinsidegrid)

-   isInsideGrid(x1: number, y1: number, x2: number, y2: number): boolean[](#isinsidegrid-1)
    
    #### Parameters
    
    -   x1: number
    -   y1: number
    -   x2: number
    -   y2: number
    
    #### Returns boolean
    

### isOffscreen[](#isoffscreen)

-   isOffscreen(x1: number, y1: number, x2: number, y2: number): boolean[](#isoffscreen-1)
    
    #### Parameters
    
    -   x1: number
    -   y1: number
    -   x2: number
    -   y2: number
    
    #### Returns boolean
    

### placeCollisionBox[](#placecollisionbox)

-   placeCollisionBox(  
        collisionBox: [SingleCollisionBox](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.SingleCollisionBox/),  
        overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/),  
        textPixelRatio: number,  
        tileID: [OverscaledTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/OverscaledTileID/),  
        unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/),  
        pitchWithMap: boolean,  
        rotateWithMap: boolean,  
        translation: \[number, number\],  
        collisionGroupPredicate?: (key: [FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)) \=> boolean,  
        getElevation?: (x: number, y: number) \=> number,  
        shift?: [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/),  
        simpleProjectionMatrix?: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/),  
    ): [PlacedBox](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PlacedBox/)[](#placecollisionbox-1)
    
    #### Parameters
    
    -   collisionBox: [SingleCollisionBox](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.SingleCollisionBox/)
    -   overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/)
    -   textPixelRatio: number
    -   tileID: [OverscaledTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/OverscaledTileID/)
    -   unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/)
    -   pitchWithMap: boolean
    -   rotateWithMap: boolean
    -   translation: \[number, number\]
    -   `Optional`collisionGroupPredicate: (key: [FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)) \=> boolean
    -   `Optional`getElevation: (x: number, y: number) \=> number
    -   `Optional`shift: [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)
    -   `Optional`simpleProjectionMatrix: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/)
    
    #### Returns [PlacedBox](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PlacedBox/)
    

### placeCollisionCircles[](#placecollisioncircles)

-   placeCollisionCircles(  
        overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/),  
        symbol: [PlacedSymbolStruct](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.PlacedSymbolStruct/),  
        lineVertexArray: [SymbolLineVertexArray](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.SymbolLineVertexArray/),  
        glyphOffsetArray: [GlyphOffsetArray](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GlyphOffsetArray/),  
        fontSize: number,  
        unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/),  
        pitchedLabelPlaneMatrix: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/),  
        showCollisionCircles: boolean,  
        pitchWithMap: boolean,  
        collisionGroupPredicate: (key: [FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)) \=> boolean,  
        circlePixelDiameter: number,  
        textPixelPadding: number,  
        translation: \[number, number\],  
        getElevation: (x: number, y: number) \=> number,  
    ): [PlacedCircles](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PlacedCircles/)[](#placecollisioncircles-1)
    
    #### Parameters
    
    -   overlapMode: [OverlapMode](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.OverlapMode/)
    -   symbol: [PlacedSymbolStruct](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.PlacedSymbolStruct/)
    -   lineVertexArray: [SymbolLineVertexArray](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.SymbolLineVertexArray/)
    -   glyphOffsetArray: [GlyphOffsetArray](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.GlyphOffsetArray/)
    -   fontSize: number
    -   unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/)
    -   pitchedLabelPlaneMatrix: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/)
    -   showCollisionCircles: boolean
    -   pitchWithMap: boolean
    -   collisionGroupPredicate: (key: [FeatureKey](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.FeatureKey/)) \=> boolean
    -   circlePixelDiameter: number
    -   textPixelPadding: number
    -   translation: \[number, number\]
    -   getElevation: (x: number, y: number) \=> number
    
    #### Returns [PlacedCircles](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PlacedCircles/)
    

### projectAndGetPerspectiveRatio[](#projectandgetperspectiveratio)

-   projectAndGetPerspectiveRatio(  
        x: number,  
        y: number,  
        unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/),  
        getElevation?: (x: number, y: number) \=> number,  
        simpleProjectionMatrix?: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/),  
    ): {  
        isOccluded: boolean;  
        perspectiveRatio: number;  
        signedDistanceFromCamera: any;  
        x: number;  
        y: number;  
    }[](#projectandgetperspectiveratio-1)
    
    #### Parameters
    
    -   x: number
    -   y: number
    -   unwrappedTileID: [UnwrappedTileID](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.UnwrappedTileID/)
    -   `Optional`getElevation: (x: number, y: number) \=> number
    -   `Optional`simpleProjectionMatrix: [mat4](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.mat4/)
    
    #### Returns {  
        isOccluded: boolean;  
        perspectiveRatio: number;  
        signedDistanceFromCamera: any;  
        x: number;  
        y: number;  
    }
    

### projectPathToScreenSpace[](#projectpathtoscreenspace)

-   projectPathToScreenSpace(  
        projectedPath: [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)\[\],  
        projectionContext: [SymbolProjectionContext](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.SymbolProjectionContext/),  
    ): [PointProjection](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PointProjection/)\[\][](#projectpathtoscreenspace-1)
    
    #### Parameters
    
    -   projectedPath: [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)\[\]
    -   projectionContext: [SymbolProjectionContext](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.SymbolProjectionContext/)
    
    #### Returns [PointProjection](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PointProjection/)\[\]
    

### queryRenderedSymbols[](#queryrenderedsymbols)

-   queryRenderedSymbols(viewportQueryGeometry: [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)\[\]): {}[](#queryrenderedsymbols-1)
    
    Because the geometries in the CollisionIndex are an approximation of the shape of symbols on the map, we use the CollisionIndex to look up the symbol part of `queryRenderedFeatures`.
    
    #### Parameters
    
    -   viewportQueryGeometry: [Point](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Point/)\[\]
    
    #### Returns {}