@mappedin/marker-cluster

An extension for Mappedin JS that allows clustering markers together.

Usage

$3

With NPM:

``zsh
npm install @mappedin/marker-cluster
`

With Yarn:

`zsh
yarn add @mappedin/marker-cluster
`

$3

`ts
import { show3dMap, Marker } from '@mappedin/mappedin-js';
import { MarkerCluster, ClusterFn } from @mappedin/marker-clustering;

const mapView = await show3dMap(...);

/**
* Add Markers to the map like normal, keeping track of markers that should be clustered.
*/
const markers: Marker[] = []
mapData.getByType('space').forEach(space => {
const marker = mapView.Markers.add(space,

/**
* Define a cluster function of type ClusterFn that returns a special Marker.
*/
const clusterFn: ClusterFn = ({ center, markers }) => {
return mapView.Markers.add(center,

/**
* Dispose the MarkerCluster when it is no longer needed.
*/
cluster.destroy();
`

$3

`ts
type MarkerClusterOptions = Partial<{
/**
* The floor the clustered marker is on. If unspecified, the floor of the first added marker will be used.
*/
floor: Floor | null;
/**
* The minimum number of markers in a cluster.
*
* @default 2
*/
minSize: number;
/**
* The debounce time in milliseconds for computing clusters when the camera is moving. If set to 0, the clusters will
* be computed on every camera frame. This could lead to performance issues if there are a lot of markers.
*
* @default 50
*/
debounce: number;
/**
* Whether the original markers should be hidden when clustered together.
*
* @default true
*/
hideClusteredMarkers: boolean;
/**
* A custom algorithm to use for clustering.
*
* @default ScreenDistanceClustering
*/
algorithm: Algorithm;
/**
* Options for the algorithm.
*/
algorithmOptions: OptionsOf;
}
`

$3

`ts
/**
* The default algorithm used by MarkerCluster is the built-in ScreenDistanceClustering algorithm. When run, this algorithm will cluster markers whose anchor coordinates are within a certain number of pixels on screen.
*/
import { ScreenDistanceClustering } from '@mappedin/marker-cluster';
`

#### Default Algorithm Options

`ts
export type ScreenDistanceClusteringOptions = Partial<{
/**
* The distance in pixels that a marker should be from another marker to be considered part of the same cluster.
*/
threshold: number;
}>;
`

$3

`ts
import { MarkeCluster, IClusterAlgorithm } from '@mappedin/marker-cluster';

/**
* Custom options can be passed to IClusterAlgorithm for stronger typing.
*/
type CustomClusteringOptions = {
threshold: number;
};

/**
* Define a custom clustering algorithm that implements IClusterAlgorithm.
*/
class CustomClustering implements IClusterAlgorithm {
/**
* A custom algorithm should probably be constructed with the MapView, but it is not necessary.
*/
constructor(mapView: MapView) {}
/**
* setOptions() is called immediately after the custom algorithm is instantiated with the value passed to "MarkerClusteringOptions.algorithmOptions". This happens in the MarkerCluster constructor.
*/
setOptions(options: CustomClusteringOptions): void {}
/**
* load() is called whenever the debounce period elapses between Camera moves. It gets passed an array of all markers that were added to the MarkerCluster.
*/
load(markers: Marker[]): void {}
/**
* getClusters() is called whenever MarkerCluster wants to update the rendered clusters. This usually happens immediately after load() is called.
*/
getClusters(): Marker[][] {}
/**
* destroy() is called when "MarkerCluster.destroy()" is called. Any resources that the ClusteringAlgorithm is holding onto can be freed up here.
*/
destroy(): void {}
}

/**
* Create a new MarkerCluster with the custom algorithm.
*/
const cluster = new MarkerCluster(mapView, clusterFn, {
algorithm: new CustomAlgorithm(mapView),
algorithmOptions: { threshold: 100 },
});
`

#### PointRBush

`ts
import { PointRBush } from '@mappedin/marker-cluster';

/**
* PointRBush is a utility class that extends the rbush package to work with { x, y } points. It can be used to help build custom clustering algorithms, but it is not necessary.
*/
const rbush = new PointRBush();

/**
* Insert, load, remove, or clear points the same as rbush.
*/
const points = [
{ x: 1, y: 2 },
{ x: 3, y: 4 },
{ x: 5, y: 6 },
];
rbush.insert(points[0]);
rbush.load([points[1], points[2]]);
rbush.remove(points[0]);
rbush.clear();

/**
* Search for points with a box the same as rbush.
*/
const results = rbush.search({ minX: 0, maxX: 5, minY: 0, maxY: 5 });

/**
* Peek at an item in the tree. This can be useful when generating clusters by removing any already clustered points and retrieving a remaining point that still needs to be clustered.
*/
const item = rbush.peek();

/**
* Check if a point is in the tree. This can be useful for optimizations if previous clusters are cached between updates.
*/
const exists = rbush.has({ x: 1, y: 2 });

/**
* Retrieve points from the tree. This can be useful for optimizations if previous clusters are cached between updates.
*/
const found = rbush.find(point => point.x > 2);
``