iosxpert / clusterkit

An iOS map clustering framework targeting MapKit and Google Maps.

---

ClusterKit is an elegant and efficiant clustering controller for maps. Its flexible architecture make it very customizable, you can use your own algorithm and even your own map provider.

Features

• Native supports of MapKit and GoogleMaps.
• Comes with 2 clustering algorithms, a Grid Based Algorithm and a Non Hierarchical Distance Based Algorithm.
• Annotations are stored in a QuadTree for efficient region queries.
• Cluster center can be switched to Centroid, Nearest Centroid, Bottom.
• Written in Objective-C with full Swift interop support.

Installation

CocoaPods

ClusterKit is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'ClusterKit'

Carthage

With Carthage, add the following to your Cartfile:

github "hulab/ClusterKit"

Maps

If you want to use ClusterKit with Mapkit or GoogleMaps, please follow the Installation Guide.

Usage

If you want to try it, simply run:

pod try ClusterKit

Or clone the repo and run pod install from the Examples directory first.

Provide the Google API Key in the AppDelegate in order to try it with GoogleMaps.

MapKit

Configure the cluster manager

CKNonHierarchicalDistanceBasedAlgorithm *algorithm = [CKNonHierarchicalDistanceBasedAlgorithm new];
self.mapView.clusterManager.algorithm = algorithm;
self.mapView.clusterManager.annotations = annotations;

Handle interactions in the map view's delegate

- (void)mapView:(MKMapView *)mapView regionDidChangeAnimated:(BOOL)animated {
    [mapView.clusterManager updateClustersIfNeeded];
}

- (void)mapView:(MKMapView *)mapView didSelectAnnotationView:(MKAnnotationView *)view {
    
    if ([view.annotation isKindOfClass:[CKCluster class]]) {
        CKCluster *cluster = view.annotation;
        
        if (cluster.count > 1) {
            [mapView showCluster:cluster animated:YES];
        }
    }
}

GoogleMaps

Configure the cluster manager

CKGridBasedAlgorithm *algorithm = [CKGridBasedAlgorithm new];
self.mapView.clusterManager.algorithm = algorithm;
self.mapView.dataSource = self;
self.mapView.clusterManager.annotations = annotations;

Handle interactions in the map view's delegate

- (void)mapView:(GMSMapView *)mapView idleAtCameraPosition:(GMSCameraPosition *)position {
    [mapView.clusterManager updateClustersIfNeeded];
}

- (BOOL)mapView:(GMSMapView *)mapView didTapMarker:(GMSMarker *)marker {
    if (marker.cluster.count > 1) {
        GMSCameraUpdate *cameraUpdate = [GMSCameraUpdate fitCluster:marker.cluster];
        [mapView animateWithCameraUpdate:cameraUpdate];
        return YES;
    }
    return NO;
}

Provide cluster marker in datasource

- (GMSMarker *)mapView:(GMSMapView *)mapView markerForCluster:(CKCluster *)cluster {
    GMSMarker *marker = [GMSMarker markerWithPosition:cluster.coordinate];
    
    if(cluster.count > 1) {
        marker.icon = <#Cluster icon#>;
    } else {
        marker.icon = <#Annotation icon#>;
    }
    
    return marker;
}

Credits

Assets by Hugo des Gayets.

License

ClusterKit is available under the MIT license. See the LICENSE file for more info.