# 地图点位聚合

**Repository Path**: qoerx/map-aggregation

## Basic Information

- **Project Name**: 地图点位聚合
- **Description**: 地图点位聚合插件是一个用于处理大量地理标记点聚合的Java库。当在地图上显示大量标记点时，直接显示所有点会导致界面混乱且性能低下。本插件通过聚合算法将相近的点合并为一个聚合点，提高地图展示效果和性能。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-11
- **Last Updated**: 2025-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java

## README

# 地图点位聚合插件说明文档

## 概述

地图点位聚合插件是一个用于处理大量地理标记点聚合的Java库。当在地图上显示大量标记点时，直接显示所有点会导致界面混乱且性能低下。本插件通过聚合算法将相近的点合并为一个聚合点，提高地图展示效果和性能。

## 核心组件

### 1. DTO (Data Transfer Objects)

#### Cluster
表示一个聚合点，包含以下属性：
- `mLatLng`: 聚合点的中心坐标
- `mClusterItems`: 包含的具体标记点列表
- `clusterItemsed`: 是否显示详细内容的标志
- `count`: 聚合点包含的标记点总数
- `latLngBounds`: 聚合点的地理边界范围

#### LatLng
表示经纬度坐标：
- `latitude`: 纬度
- `longitude`: 经度

#### LatLngBounds
表示一个矩形地理区域范围：
- `southwest`: 西南角坐标（最小点经纬度）
- `northeast`: 东北角坐标（最大点经纬度）

### 2. Item (聚合元素)

#### ClusterItem (接口)
所有可聚合元素需要实现的接口，提供`getPosition()`方法获取元素地理位置。

#### RegionItem (实现类)
区域聚合元素的实现，包含：
- `mLatLng`: 标记点地理坐标
- `mapData`: 关联的业务数据

### 3. Result (结果集)

#### MapResult
封装聚合结果：
- `total`: 总坐标点数
- `clusters`: 聚合点列表

### 4. Template (模板)

#### MarkerCluster
聚合点计算的抽象模板类，提供：
- `getMapClusters()`: 获取聚合结果的主要方法
- `getClusterItem()`: 抽象方法，需要子类实现数据转换
- 聚合算法实现（距离算法、方格算法等）

## 使用方法

1. 继承`MarkerCluster`类并实现`getClusterItem()`方法
2. 调用`getMapClusters()`方法传入原始数据和参数
3. 处理返回的`MapResult`对象

## 聚合算法

系统支持多种聚合算法：
1. 距离算法：根据两点间距离判断是否聚合
2. 方格算法：将地图划分为网格，同一网格内的点聚合
3. 混合算法：结合距离和方格算法

## 参数说明

- `mPXInMeters`: 每像素代表的实际地图距离(米)
- `mClusterSize`: 自定义多少像素聚合
- `visibleBounds`: 当前屏幕可见范围
- `zoom`: 当前地图缩放级别
- `isClusterItems`: 是否保存聚合点内详细信息

## 性能优化

- 当缩放级别超过19级时，不进行聚合
- 只保留单一标记点的详细信息，聚合点仅保留数量