MarkerClustering.js

/**
 * Copyright 2016 NAVER Corp.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * 마커 클러스터링을 정의합니다.
 * @param {Object} options 마커 클러스터링 옵션
 */
var MarkerClustering = function (options) {
  // 기본 값입니다.
  this.DEFAULT_OPTIONS = {
    // 클러스터 마커를 올릴 지도입니다.
    map: null,
    // 클러스터 마커를 구성할 마커입니다.
    markers: [],
    // 클러스터 마커 클릭 시 줌 동작 여부입니다.
    disableClickZoom: true,
    // 클러스터를 구성할 최소 마커 수입니다.
    minClusterSize: 2,
    // 클러스터 마커로 표현할 최대 줌 레벨입니다. 해당 줌 레벨보다 높으면, 클러스터를 구성하고 있는 마커를 노출합니다.
    maxZoom: 13,
    // 클러스터를 구성할 그리드 크기입니다. 단위는 픽셀입니다.
    gridSize: 100,
    // 클러스터 마커의 아이콘입니다. NAVER Maps JavaScript API v3에서 제공하는 아이콘, 심볼, HTML 마커 유형을 모두 사용할 수 있습니다.
    icons: [],
    // 클러스터 마커의 아이콘 배열에서 어떤 아이콘을 선택할 것인지 인덱스를 결정합니다.
    indexGenerator: [10, 100, 200, 500, 1000],
    // 클러스터 마커의 위치를 클러스터를 구성하고 있는 마커의 평균 좌표로 할 것인지 여부입니다.
    averageCenter: false,
    // 클러스터 마커를 갱신할 때 호출하는 콜백함수입니다. 이 함수를 통해 클러스터 마커에 개수를 표현하는 등의 엘리먼트를 조작할 수 있습니다.
    stylingFunction: function () {},
  };

  this._clusters = [];

  this._mapRelations = null;
  this._markerRelations = [];

  this.setOptions(
    naver.maps.Util.extend({}, this.DEFAULT_OPTIONS, options),
    true
  );
  this.setMap(options.map || null);
};

naver.maps.Util.ClassExtend(MarkerClustering, naver.maps.OverlayView, {
  onAdd: function () {
    var map = this.getMap();

    this._mapRelations = naver.maps.Event.addListener(
      map,
      "idle",
      naver.maps.Util.bind(this._onIdle, this)
    );

    if (this.getMarkers().length > 0) {
      this._createClusters();
      this._updateClusters();
    }
  },

  draw: naver.maps.Util.noop,

  onRemove: function () {
    naver.maps.Event.removeListener(this._mapRelation);

    this._clearClusters();

    this._geoTree = null;
    this._mapRelation = null;
  },

  /**
   * 마커 클러스터링 옵션을 설정합니다. 설정한 옵션만 반영됩니다.
   * @param {Object | string} newOptions 옵션
   */
  setOptions: function (newOptions) {
    var _this = this;

    if (typeof newOptions === "string") {
      var key = newOptions,
        value = arguments[1];

      _this.set(key, value);
    } else {
      var isFirst = arguments[1];

      naver.maps.Util.forEach(newOptions, function (value, key) {
        if (key !== "map") {
          _this.set(key, value);
        }
      });

      if (newOptions.map && !isFirst) {
        _this.setMap(newOptions.map);
      }
    }
  },

  /**
   * 마커 클러스터링 옵션을 반환합니다. 특정 옵션 이름을 지정하지 않으면, 모든 옵션을 반환합니다.
   * @param {string} key 반환받을 옵션 이름
   * @return {Any} 옵션
   */
  getOptions: function (key) {
    var _this = this,
      options = {};

    if (key !== undefined) {
      return _this.get(key);
    } else {
      naver.maps.Util.forEach(_this.DEFAULT_OPTIONS, function (value, key) {
        options[key] = _this.get(key);
      });

      return options;
    }
  },

  /**
   * 클러스터를 구성하는 최소 마커 수를 반환합니다.
   * @return {number} 클러스터를 구성하는 최소 마커 수
   */
  getMinClusterSize: function () {
    return this.getOptions("minClusterSize");
  },

  /**
   * 클러스터를 구성하는 최소 마커 수를 설정합니다.
   * @param {number} size 클러스터를 구성하는 최소 마커 수
   */
  setMinClusterSize: function (size) {
    this.setOptions("minClusterSize", size);
  },

  /**
   * 클러스터 마커를 노출할 최대 줌 레벨을 반환합니다.
   * @return {number} 클러스터 마커를 노출할 최대 줌 레벨
   */
  getMaxZoom: function () {
    return this.getOptions("maxZoom");
  },

  /**
   * 클러스터 마커를 노출할 최대 줌 레벨을 설정합니다.
   * @param {number} zoom 클러스터 마커를 노출할 최대 줌 레벨
   */
  setMaxZoom: function (zoom) {
    this.setOptions("maxZoom", zoom);
  },

  /**
   * 클러스터를 구성할 그리드 크기를 반환합니다. 단위는 픽셀입니다.
   * @return {number} 클러스터를 구성할 그리드 크기
   */
  getGridSize: function () {
    return this.getOptions("gridSize");
  },

  /**
   * 클러스터를 구성할 그리드 크기를 설정합니다. 단위는 픽셀입니다.
   * @param {number} size 클러스터를 구성할 그리드 크기
   */
  setGridSize: function (size) {
    this.setOptions("gridSize", size);
  },

  /**
   * 클러스터 마커의 아이콘을 결정하는 인덱스 생성기를 반환합니다.
   * @return {Array | Function} 인덱스 생성기
   */
  getIndexGenerator: function () {
    return this.getOptions("indexGenerator");
  },

  /**
   * 클러스터 마커의 아이콘을 결정하는 인덱스 생성기를 설정합니다.
   * @param {Array | Function} indexGenerator 인덱스 생성기
   */
  setIndexGenerator: function (indexGenerator) {
    this.setOptions("indexGenerator", indexGenerator);
  },

  /**
   * 클러스터로 구성할 마커를 반환합니다.
   * @return {Array.<naver.maps.Marker>} 클러스터로 구성할 마커
   */
  getMarkers: function () {
    return this.getOptions("markers");
  },

  /**
   * 클러스터로 구성할 마커를 설정합니다.
   * @param {Array.<naver.maps.Marker>} markers 클러스터로 구성할 마커
   */
  setMarkers: function (markers) {
    this.setOptions("markers", markers);
  },

  /**
   * 클러스터 마커 아이콘을 반환합니다.
   * @return {Array.<naver.maps.Marker~ImageIcon | naver.maps.Marker~SymbolIcon | naver.maps.Marker~HtmlIcon>} 클러스터 마커 아이콘
   */
  getIcons: function () {
    return this.getOptions("icons");
  },

  /**
   * 클러스터 마커 아이콘을 설정합니다.
   * @param {Array.<naver.maps.Marker~ImageIcon | naver.maps.Marker~SymbolIcon | naver.maps.Marker~HtmlIcon>} icons 클러스터 마커 아이콘
   */
  setIcons: function (icons) {
    this.setOptions("icons", icons);
  },

  /**
   * 클러스터 마커의 엘리먼트를 조작할 수 있는 스타일링 함수를 반환합니다.
   * @return {Funxtion} 콜백함수
   */
  getStylingFunction: function () {
    return this.getOptions("stylingFunction");
  },

  /**
   * 클러스터 마커의 엘리먼트를 조작할 수 있는 스타일링 함수를 설정합니다.
   * @param {Function} func 콜백함수
   */
  setStylingFunction: function (func) {
    this.setOptions("stylingFunction", func);
  },

  /**
   * 클러스터 마커를 클릭했을 때 줌 동작 수행 여부를 반환합니다.
   * @return {boolean} 줌 동작 수행 여부
   */
  getDisableClickZoom: function () {
    return this.getOptions("disableClickZoom");
  },

  /**
   * 클러스터 마커를 클릭했을 때 줌 동작 수행 여부를 설정합니다.
   * @param {boolean} flag 줌 동작 수행 여부
   */
  setDisableClickZoom: function (flag) {
    this.setOptions("disableClickZoom", flag);
  },

  /**
   * 클러스터 마커의 위치를 클러스터를 구성하고 있는 마커의 평균 좌표로 할 것인지 여부를 반환합니다.
   * @return {boolean} 평균 좌표로 클러스터링 여부
   */
  getAverageCenter: function () {
    return this.getOptions("averageCenter");
  },

  /**
   * 클러스터 마커의 위치를 클러스터를 구성하고 있는 마커의 평균 좌표로 할 것인지 여부를 설정합니다.
   * @param {boolean} averageCenter 평균 좌표로 클러스터링 여부
   */
  setAverageCenter: function (averageCenter) {
    this.setOptions("averageCenter", averageCenter);
  },

  // KVO 이벤트 핸들러
  changed: function (key, value) {
    if (!this.getMap()) return;

    switch (key) {
      case "marker":
      case "minClusterSize":
      case "gridSize":
      case "averageCenter":
        this._redraw();
        break;
      case "indexGenerator":
      case "icons":
        this._clusters.forEach(function (cluster) {
          cluster.updateIcon();
        });
        break;
      case "maxZoom":
        this._clusters.forEach(function (cluster) {
          if (cluster.getCount() > 1) {
            cluster.checkByZoomAndMinClusterSize();
          }
        });
        break;
      case "stylingFunction":
        this._clusters.forEach(function (cluster) {
          cluster.updateCount();
        });
        break;
      case "disableClickZoom":
        var exec = "enableClickZoom";

        if (value) {
          exec = "disableClickZoom";
        }

        this._clusters.forEach(function (cluster) {
          cluster[exec]();
        });
        break;
    }
  },

  /**
   * 현재 지도 경계 영역 내의 마커에 대해 클러스터를 생성합니다.
   * @private
   */
  _createClusters: function () {
    var map = this.getMap();

    if (!map) return;

    var bounds = map.getBounds(),
      markers = this.getMarkers();

    for (var i = 0, ii = markers.length; i < ii; i++) {
      var marker = markers[i],
        position = marker.getPosition();

      if (!bounds.hasLatLng(position)) continue;

      var closestCluster = this._getClosestCluster(position);

      closestCluster.addMarker(marker);

      this._markerRelations.push(
        naver.maps.Event.addListener(
          marker,
          "dragend",
          naver.maps.Util.bind(this._onDragEnd, this)
        )
      );
    }
  },

  /**
   * 클러스터의 아이콘, 텍스트를 갱신합니다.
   * @private
   */
  _updateClusters: function () {
    var clusters = this._clusters;

    for (var i = 0, ii = clusters.length; i < ii; i++) {
      clusters[i].updateCluster();
    }
  },

  /**
   * 클러스터를 모두 제거합니다.
   * @private
   */
  _clearClusters: function () {
    var clusters = this._clusters;

    for (var i = 0, ii = clusters.length; i < ii; i++) {
      clusters[i].destroy();
    }

    naver.maps.Event.removeListener(this._markerRelations);

    this._markerRelations = [];
    this._clusters = [];
  },

  /**
   * 생성된 클러스터를 모두 제거하고, 다시 생성합니다.
   * @private
   */
  _redraw: function () {
    this._clearClusters();
    this._createClusters();
    this._updateClusters();
  },

  /**
   * 전달된 위/경도에서 가장 가까운 클러스터를 반환합니다. 없으면 새로 클러스터를 생성해 반환합니다.
   * @param {naver.maps.LatLng} position 위/경도
   * @return {Cluster} 클러스터
   */
  _getClosestCluster: function (position) {
    var proj = this.getProjection(),
      clusters = this._clusters,
      closestCluster = null,
      distance = Infinity;

    for (var i = 0, ii = clusters.length; i < ii; i++) {
      var cluster = clusters[i],
        center = cluster.getCenter();

      if (cluster.isInBounds(position)) {
        var delta = proj.getDistance(center, position);

        if (delta < distance) {
          distance = delta;
          closestCluster = cluster;
        }
      }
    }

    if (!closestCluster) {
      closestCluster = new Cluster(this);
      this._clusters.push(closestCluster);
    }

    return closestCluster;
  },

  /**
   * 지도의 Idle 상태 이벤트 핸들러입니다.
   */
  _onIdle: function () {
    this._redraw();
  },

  /**
   * 각 마커의 드래그 종료 이벤트 핸들러입니다.
   */
  _onDragEnd: function () {
    this._redraw();
  },
});

/**
 * 마커를 가지고 있는 클러스터를 정의합니다.
 * @param {MarkerClustering} markerClusterer
 */
var Cluster = function (markerClusterer) {
  this._clusterCenter = null;
  this._clusterBounds = null;
  this._clusterMarker = null;
  this._relation = null;

  this._clusterMember = [];

  this._markerClusterer = markerClusterer;
};

Cluster.prototype = {
  constructor: Cluster,

  /**
   * 클러스터에 마커를 추가합니다.
   * @param {naver.maps.Marker} marker 클러스터에 추가할 마커
   */
  addMarker: function (marker) {
    if (this._isMember(marker)) return;

    if (!this._clusterCenter) {
      var position = marker.getPosition();

      this._clusterCenter = position;
      this._clusterBounds = this._calcBounds(position);
    }

    this._clusterMember.push(marker);
  },

  /**
   * 클러스터를 제거합니다.
   */
  destroy: function () {
    naver.maps.Event.removeListener(this._relation);

    var members = this._clusterMember;

    for (var i = 0, ii = members.length; i < ii; i++) {
      members[i].setMap(null);
    }

    this._clusterMarker.setMap(null);

    this._clusterMarker = null;
    this._clusterCenter = null;
    this._clusterBounds = null;
    this._relation = null;

    this._clusterMember = [];
  },

  /**
   * 클러스터 중심점을 반환합니다.
   * @return {naver.maps.LatLng} 클러스터 중심점
   */
  getCenter: function () {
    return this._clusterCenter;
  },

  /**
   * 클러스터 경계 영역을 반환합니다.
   * @return {naver.maps.LatLngBounds} 클러스터 경계 영역
   */
  getBounds: function () {
    return this._clusterBounds;
  },

  /**
   * 클러스터를 구성하는 마커 수를 반환합니다.
   * @return {number} 클러스터를 구성하는 마커 수
   */
  getCount: function () {
    return this._clusterMember.length;
  },

  /**
   * 현재의 클러스터 멤버 마커 객체를 반환합니다.
   * @return {naver.maps.Marker[]} 클러스터를 구성하는 마커 객체 집합
   */
  getClusterMember: function () {
    return this._clusterMember;
  },

  /**
   * 전달된 위/경도가 클러스터 경계 영역 내에 있는지 여부를 반환합니다.
   * @param {naver.maps.LatLng} latlng 위/경도
   * @return {boolean} 클러스터 경계 영역 내의 위치 여부
   */
  isInBounds: function (latlng) {
    return this._clusterBounds && this._clusterBounds.hasLatLng(latlng);
  },

  /**
   * 클러스터 마커 클릭 시 줌 동작을 수행하도록 합니다.
   */
  enableClickZoom: function () {
    if (this._relation) return;

    var map = this._markerClusterer.getMap();

    this._relation = naver.maps.Event.addListener(
      this._clusterMarker,
      "click",
      naver.maps.Util.bind(function (e) {
        map.morph(e.coord, map.getZoom() + 1);
      }, this)
    );
  },

  /**
   * 클러스터 마커 클릭 시 줌 동작을 수행하지 않도록 합니다.
   */
  disableClickZoom: function () {
    if (!this._relation) return;

    naver.maps.Event.removeListener(this._relation);
    this._relation = null;
  },

  /**
   * 클러스터 마커가 없으면 클러스터 마커를 생성하고, 클러스터 마커를 갱신합니다.
   * - 클러스터 마커 아이콘
   * - 마커 개수
   * - 클러스터 마커 노출 여부
   */
  updateCluster: function () {
    if (!this._clusterMarker) {
      var position;

      if (this._markerClusterer.getAverageCenter()) {
        position = this._calcAverageCenter(this._clusterMember);
      } else {
        position = this._clusterCenter;
      }

      this._clusterMarker = new naver.maps.Marker({
        position: position,
        map: this._markerClusterer.getMap(),
      });

      if (!this._markerClusterer.getDisableClickZoom()) {
        this.enableClickZoom();
      }
    }

    this.updateIcon();
    this.updateCount();

    this.checkByZoomAndMinClusterSize();
  },

  /**
   * 조건에 따라 클러스터 마커를 노출하거나, 노출하지 않습니다.
   */
  checkByZoomAndMinClusterSize: function () {
    var clusterer = this._markerClusterer,
      minClusterSize = clusterer.getMinClusterSize(),
      maxZoom = clusterer.getMaxZoom(),
      currentZoom = clusterer.getMap().getZoom();

    if (this.getCount() < minClusterSize) {
      this._showMember();
    } else {
      this._hideMember();

      if (maxZoom <= currentZoom) {
        this._showMember();
      }
    }
  },

  /**
   * 클러스터를 구성하는 마커 수를 갱신합니다.
   */
  updateCount: function () {
    var stylingFunction = this._markerClusterer.getStylingFunction();

    stylingFunction && stylingFunction(this._clusterMarker, this.getCount());
  },

  /**
   * 클러스터 마커 아이콘을 갱신합니다.
   */
  updateIcon: function () {
    var count = this.getCount(),
      index = this._getIndex(count),
      icons = this._markerClusterer.getIcons();

    index = Math.max(index, 0);
    index = Math.min(index, icons.length - 1);

    this._clusterMarker.setIcon(icons[index]);
  },

  /**
   * 클러스터를 구성하는 마커를 노출합니다. 이때에는 클러스터 마커를 노출하지 않습니다.
   * @private
   */
  _showMember: function () {
    var map = this._markerClusterer.getMap(),
      marker = this._clusterMarker,
      members = this._clusterMember;

    for (var i = 0, ii = members.length; i < ii; i++) {
      members[i].setMap(map);
    }

    if (marker) {
      marker.setMap(null);
    }
  },

  /**
   * 클러스터를 구성하는 마커를 노출하지 않습니다. 이때에는 클러스터 마커를 노출합니다.
   * @private
   */
  _hideMember: function () {
    var map = this._markerClusterer.getMap(),
      marker = this._clusterMarker,
      members = this._clusterMember;

    for (var i = 0, ii = members.length; i < ii; i++) {
      members[i].setMap(null);
    }

    if (marker && !marker.getMap()) {
      marker.setMap(map);
    }
  },

  /**
   * 전달된 위/경도를 중심으로 그리드 크기만큼 확장한 클러스터 경계 영역을 반환합니다.
   * @param {naver.maps.LatLng} position 위/경도
   * @return {naver.maps.LatLngBounds} 클러스터 경계 영역
   * @private
   */
  _calcBounds: function (position) {
    var map = this._markerClusterer.getMap(),
      bounds = new naver.maps.LatLngBounds(position.clone(), position.clone()),
      mapBounds = map.getBounds(),
      proj = map.getProjection(),
      map_max_px = proj.fromCoordToOffset(mapBounds.getNE()),
      map_min_px = proj.fromCoordToOffset(mapBounds.getSW()),
      max_px = proj.fromCoordToOffset(bounds.getNE()),
      min_px = proj.fromCoordToOffset(bounds.getSW()),
      gridSize = this._markerClusterer.getGridSize() / 2;

    max_px.add(gridSize, -gridSize);
    min_px.add(-gridSize, gridSize);

    var max_px_x = Math.min(map_max_px.x, max_px.x),
      max_px_y = Math.max(map_max_px.y, max_px.y),
      min_px_x = Math.max(map_min_px.x, min_px.x),
      min_px_y = Math.min(map_min_px.y, min_px.y),
      newMax = proj.fromOffsetToCoord(new naver.maps.Point(max_px_x, max_px_y)),
      newMin = proj.fromOffsetToCoord(new naver.maps.Point(min_px_x, min_px_y));

    return new naver.maps.LatLngBounds(newMin, newMax);
  },

  /**
   * 클러스터를 구성하는 마커 수에 따라 노출할 아이콘을 결정하기 위한 인덱스를 반환합니다.
   * @param {number} count 클러스터를 구성하는 마커 수
   * @return {number} 인덱스
   * @private
   */
  _getIndex: function (count) {
    var indexGenerator = this._markerClusterer.getIndexGenerator();

    if (naver.maps.Util.isFunction(indexGenerator)) {
      return indexGenerator(count);
    } else if (naver.maps.Util.isArray(indexGenerator)) {
      var index = 0;

      for (var i = index, ii = indexGenerator.length; i < ii; i++) {
        var factor = indexGenerator[i];

        if (count < factor) break;

        index++;
      }

      return index;
    }
  },

  /**
   * 전달된 마커가 이미 클러스터에 속해 있는지 여부를 반환합니다.
   * @param {naver.maps.Marker} marker 마커
   * @return {boolean} 클러스터에 속해 있는지 여부
   * @private
   */
  _isMember: function (marker) {
    return this._clusterMember.indexOf(marker) !== -1;
  },

  /**
   * 전달된 마커들의 중심 좌표를 반환합니다.
   * @param {Array.<naver.maps.Marker>} markers 마커 배열
   * @return {naver.maps.Point} 마커들의 중심 좌표
   * @private
   */
  _calcAverageCenter: function (markers) {
    var numberOfMarkers = markers.length;
    var averageCenter = [0, 0];

    for (var i = 0; i < numberOfMarkers; i++) {
      averageCenter[0] += markers[i].position.x;
      averageCenter[1] += markers[i].position.y;
    }

    averageCenter[0] /= numberOfMarkers;
    averageCenter[1] /= numberOfMarkers;

    return new naver.maps.Point(averageCenter[0], averageCenter[1]);
  },
};