### C Hello World

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/format.md

A basic C program that prints "Hello world!". This is a standard entry point for C programming examples.

```c
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}
```

--------------------------------

### Install GoTrackIt

Source: https://github.com/zdsjjttlg/trackit/blob/main/README_EN.md

Instructions on how to install the GoTrackIt package using pip. It is recommended to install via pip rather than downloading directly from the GitHub repository.

```bash
pip install gotrackit
```

--------------------------------

### Install gotrackit Package

Source: https://github.com/zdsjjttlg/trackit/blob/main/README_EN.md

Installs the gotrackit package from PyPI using the specified index URL.

```shell
pip install -i https://pypi.org/simple/ gotrackit
```

--------------------------------

### Python: Map Matching with Multi-core Parallel Execution

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

This snippet demonstrates how to perform map matching using multiple CPU cores by calling `multi_core_execute` and specifying the number of cores. This can significantly speed up processing for large datasets. The setup is otherwise similar to standard map matching.

```python
import geopandas as gpd
import pandas as pd
from trackit.core.network.network import Net
from trackit.core.map_match.map_match import MapMatch

link = gpd.read_file(r'./data/input/modifiedConn_link.shp')
node = gpd.read_file(r'./data/input/modifiedConn_node.shp')
my_net = Net(link_gdf=link, node_gdf=node)
my_net.init_net()  # net初始化

gps_df = pd.read_csv(r'./data/input/example_gps.csv')

mpm = MapMatch(net=my_net, flag_name='xa_sample', use_sub_net=True, 
               gps_buffer=100, top_k=20, dense_gps=False,
               use_heading_inf=True, omitted_l=6.0,
               del_dwell=True, dwell_l_length=50.0, dwell_n=0,
               export_html=True, export_geo_res=True, use_gps_source=True,
               gps_radius=15.0, export_all_agents=False,
               out_fldr=r'./data/output/match')
# execute函数返回三个结果:
# 第一个是匹配结果表、第二个是警告信息、第三个是错误信息
match_res, may_error_info, error_info = mpm.multi_core_execute(gps_df=gps_df, core_num=2)
match_res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)
```

--------------------------------

### C++ Hello World

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/format.md

A basic C++ program that prints "Hello world!". This demonstrates standard output in C++.

```c++
#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}
```

--------------------------------

### Status Transfer Warning Example

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Illustrates `UserWarning` messages generated when adjacent GPS points match road segments that are topologically disconnected. This indicates potential road data gaps or inconsistencies in the road network.

```c
UserWarning: gps seq: 10 -> 11 problem with state transfer, from_link:(60, 59) -> to_link:(98, 25)
UserWarning: gps seq: 15 -> 16 problem with state transfer, from_link:(15, 38) -> to_link:(78, 26)
```

--------------------------------

### Net Class API Documentation

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/Func&API/Net.md

Documentation for the Net class methods, including initialization and shortest path calculations.

```APIDOC
src.gotrackit.map.Net.Net:
  __init__(self, ...)
    Initializes the Net object.
    This method sets up the internal state for network operations.
    Parameters:
      self: The instance of the Net class.
      ...: Additional arguments for initialization (details not provided).
    Returns: None

  shortest_k_paths(self, start_node, end_node, k, ...)
    Calculates the K shortest paths between two nodes in the network.
    This method is crucial for finding multiple optimal routes.
    Parameters:
      self: The instance of the Net class.
      start_node: The starting node for pathfinding.
      end_node: The destination node for pathfinding.
      k: The number of shortest paths to find.
      ...: Additional parameters that may influence pathfinding (e.g., edge weights, constraints).
    Returns: A list or structure containing the K shortest paths and their associated costs or metrics.
```

--------------------------------

### Road Segment Association Warning Example

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Shows `UserWarning` for GPS points that cannot be associated with any road segment within the specified buffer. These points are excluded from path matching calculations, often due to location outside the road network or small buffer sizes.

```c
UserWarning: the GPS point with seq: [1024, 1025] is not associated with any candidate road segment
and will not be used for path matching calculation...
```

--------------------------------

### HTTP Methods

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/format.md

Common HTTP methods used for interacting with web resources. Includes descriptions for fetching, updating, and deleting resources.

```APIDOC
GET: Fetch resource
PUT: Update resource
DELETE: Delete resource
```

--------------------------------

### Python MapMatch: Set speed_threshold to 10000km/h

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/blog/posts/speed_threshold参数.md

Illustrates initializing `MapMatch` with a significantly higher `speed_threshold` of 10000 km/h. This example shows how a relaxed speed limit can lead to different path validation outcomes, potentially accepting paths that would be rejected with a lower threshold. Dependencies include pandas and geopandas.

```python
import pandas as pd
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import MapMatch

gps_df = pd.read_csv(r'./20240320_to_20240320_data_chunk_0.csv')

link = gpd.read_file(r'./merge_FinalLink.shp', encoding='gbk')
node = gpd.read_file(r'./merge_FinalNode.shp', encoding='gbk')

my_net = Net(link_gdf=link, prj_cache=True,
             node_gdf=node, not_conn_cost=2500.0, cut_off=600.0, 
             grid_len=4000, is_hierarchical=True)
my_net.init_net()  # net初始化

mpm = MapMatch(net=my_net, flag_name='id1', time_unit='ms',
               gps_buffer=900.0, top_k=30,
               speed_threshold=10000,
               dense_interval=400.0, dense_gps=True,
               export_html=True, export_geo_res=True, 
               out_fldr=r'./output/')
match_res, warn_info, error_info = mpm.execute(gps_df=gps_df,)
```

--------------------------------

### Python: Standard Map Matching

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

This snippet demonstrates the standard map matching process using the MapMatch class. It initializes a network from shapefiles and then executes the matching process on GPS data. The output includes the match results, warnings, and errors.

```python
import geopandas as gpd
import pandas as pd
from trackit.core.network.network import Net
from trackit.core.map_match.map_match import MapMatch

link = gpd.read_file(r'./data/input/modifiedConn_link.shp')
node = gpd.read_file(r'./data/input/modifiedConn_node.shp')
my_net = Net(link_gdf=link, node_gdf=node)
my_net.init_net()  # net初始化

gps_df = pd.read_csv(r'./data/input/example_gps.csv')

mpm = MapMatch(net=my_net, flag_name='xa_sample', use_sub_net=True, 
               gps_buffer=100, top_k=20, dense_gps=False,
               use_heading_inf=True, omitted_l=6.0,
               del_dwell=True, dwell_l_length=50.0, dwell_n=0,
               export_html=True, export_geo_res=True, use_gps_source=True,
               gps_radius=15.0, export_all_agents=False,
               out_fldr=r'./data/output/match')
# execute函数返回三个结果:
# 第一个是匹配结果表、第二个是警告信息、第三个是错误信息
match_res, may_error_info, error_info = mpm.execute(gps_df=gps_df)
match_res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)
```

--------------------------------

### MapMatch Initialization and HTML Export

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Demonstrates how to control the generation of HTML visualization files during the MapMatch process. Setting `export_html` to True generates detailed visual logs for debugging trajectory matching.

```python
# Example of MapMatch initialization parameter
# map_match = MapMatch(..., export_html=True, out_fldr='output_directory')
```

--------------------------------

### Map Matching with Spatial Stratification

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Demonstrates initializing a network from shapefiles and performing map matching using the MapMatch class. It covers setting various parameters for the matching process and saving the results to a CSV file. This snippet is particularly relevant for large-scale networks.

```python
import geopandas as gpd
import pandas as pd
from trackit.map_matching.map_match import MapMatch
from trackit.network.network import Net

# Load network data
link = gpd.read_file(r'./data/input/modifiedConn_link.shp')
node = gpd.read_file(r'./data/input/modifiedConn_node.shp')

# Initialize network with spatial stratification enabled
my_net = Net(link_gdf=link, node_gdf=node, is_hierarchical=True)
my_net.init_net()  # Initialize the network

# Load GPS data
gps_df = pd.read_csv(r'./data/input/example_gps.csv')

# Configure and initialize MapMatch
mpm = MapMatch(net=my_net, flag_name='xa_sample', use_sub_net=True, 
                   gps_buffer=100, top_k=20, dense_gps=False,
                   use_heading_inf=True, omitted_l=6.0,
                   del_dwell=True, dwell_l_length=50.0, dwell_n=0,
                   export_html=True, export_geo_res=True, use_gps_source=True,
                   gps_radius=15.0, export_all_agents=False,
                   out_fldr=r'./data/output/match')

# Execute map matching
# The execute function returns: match results table, warning info, error info
match_res, may_error_info, error_info = mpm.execute(gps_df=gps_df)

# Save the matching results to a CSV file
match_res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)
```

--------------------------------

### Generate Destination-based Trips with TripGeneration

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/轨迹生产.md

Shows how to use the `generate_destined_trips` method from the `TripGeneration` class for generating trips along pre-defined node paths. This involves obtaining node paths (e.g., using shortest path algorithms from the `Net` object) and passing them to the generation method with output configuration.

```python
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.generation.SampleTrip import TripGeneration

if __name__ == '__main__':
    # 1.构读取link和node
    link = gpd.read_file(r'./data/input/link.shp')
    node = gpd.read_file(r'./data/input/node.shp')

    # 1.构建一个net, 要求路网线层和路网点层必须是WGS-84, EPSG:4326 地理坐标系
    my_net = Net(link_gdf=link, node_gdf=node)
    my_net.init_net()  # 路网对象初始化
    
    # 新建一个行程生成类
    ts = TripGeneration(net=my_net, loc_error_sigma=50.0, loc_frequency=30, time_step=0.1)
    
    # 利用net对象的k节点间的K最短路接口获取节点路径序列
    node_path = list()
    
    # 从节点110943到达节点225405的最短6条路径
    for path in my_net.shortest_k_paths(110943, 225405, 6):
        node_path.append(path)

    # 依据指定的OD起终点生成trip
    ts.generate_destined_trips(node_paths=node_path, out_fldr=r'./data/output/sample_gps', time_format="%Y-%m-%d %H:%M:%S.%f",
                               agent_flag='0916-agent', instant_output=False, file_type='shp',
                               start_year=2023)
```

--------------------------------

### Generate SUMO Configuration File

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/案例介绍/匹配结果转微观仿真.md

Creates the SUMO simulation configuration file (.sumocfg). This function requires the paths to the SUMO network (.net.xml) and route (.rou.xml) files, along with the output directory and simulation time range.

```Python
from gotrackit.netxfer.SumoConvert import SumoConvert
import os

# Assuming fldr and sc (SumoConvert instance) are defined
# fldr = ...
# sc = SumoConvert()

# Specify absolute paths for .net.xml and .rou.xml files
# Specify output directory and simulation start/end times
sc.generate_sumocfg(net_file_path=os.path.join(fldr, 'input', 'ns.net.xml'),
                    rou_file_path=os.path.join(fldr, 'output/sim/flow.rou.xml'),
                    out_fldr=os.path.join(fldr, 'output/sim'), start_time=0, end_time=3600)
```

--------------------------------

### Execute Path Matching

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Initializes the MapMatch class with the prepared Net object and GPS data. It configures various matching parameters such as sub-network usage, GPS buffer, top-k candidates, heading information, dwell point handling, and output settings. The execute function returns the matching results, warnings, and error information.

```python
mpm = MapMatch(net=my_net, flag_name='xa_sample', # 指定项目名称xa_sample
               use_sub_net=True, # 启用子网络
               gps_buffer=100, top_k=20, # GPS点空间关联半径取100米，选取GPS点100米范围内最近的20个路段作为候选路段
               dense_gps=False, # 不增密GPS点
               use_heading_inf=True, omitted_l=6.0,  # 启用GPS航向角矫正，若前后点GPS距离<=6米，将忽略航向角的修正
               del_dwell=True, dwell_l_length=50.0, dwell_n=0,  # 停留点删除参数
               export_html=True, export_geo_res=True, use_gps_source=True,  # 输出设置参数
               gps_radius=15.0, export_all_agents=False, # 输出设置参数
               out_fldr=r'./data/output/match_visualization/xa_sample')  # 输出设置参数

# execute函数返回三个结果:
# 第一个是匹配结果表、第二个是警告信息、第三个是错误信息
match_res, warn_info, error_info = mpm.execute(gps_df=gps_df)
match_res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)
```

--------------------------------

### SumoConvert Class Methods

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/Func&API/SumoConvert.md

This section details the methods available within the SumoConvert class. These methods are designed for various data processing tasks, including initialization, network shapefile retrieval, HD map generation, route matching, and SUMO configuration file generation.

```APIDOC
src.gotrackit.netxfer.SumoConvert.SumoConvert.__init__
  - Initializes the SumoConvert object.
  - Parameters: Not specified in provided text.
  - Returns: Not specified in provided text.

src.gotrackit.netxfer.SumoConvert.SumoConvert.get_net_shp
  - Retrieves network shapefile data.
  - Parameters: Not specified in provided text.
  - Returns: Not specified in provided text.

src.gotrackit.netxfer.SumoConvert.SumoConvert.generate_hd_map
  - Generates a high-definition map.
  - Parameters: Not specified in provided text.
  - Returns: Not specified in provided text.

src.gotrackit.netxfer.SumoConvert.SumoConvert.match2rou
  - Matches data to a route.
  - Parameters: Not specified in provided text.
  - Returns: Not specified in provided text.

src.gotrackit.netxfer.SumoConvert.SumoConvert.generate_sumocfg
  - Generates a SUMO configuration file.
  - Parameters: Not specified in provided text.
  - Returns: Not specified in provided text.
```

--------------------------------

### TrackIt Matching Acceleration Strategies

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Outlines four strategies provided by TrackIt to accelerate the trajectory matching process. These include pre-calculating shortest paths, parallel processing, road network simplification, and spatial hierarchical association.

```APIDOC
Matching Acceleration Strategies:

1.  **Pre-calculate Shortest Paths**: Compute shortest paths for road network nodes beforehand and store them in memory to reduce runtime computation. Requires significant memory.
2.  **Parallel Matching**: Group positioning data by agent_id and use multiple CPU cores to process different data groups concurrently. Requires significant memory.
3.  **Road Network Simplification**: Simplify road network linestrings to reduce computation time for projection parameters.
4.  **Spatial Hierarchical Association**: Employ a spatial hierarchical strategy to decrease the time spent on spatial association.
```

--------------------------------

### Initialize and Execute MapMatch

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/案例介绍/匹配结果转微观仿真.md

Initializes the MapMatch class with network, export options, and matching parameters. The execute method processes GPS data to produce match results, warnings, and errors.

```Python
from gotrackit.map_match import MapMatch
import os

# Assuming my_net, gps_df, and fldr are defined elsewhere
# my_net = ...
# gps_df = ...
# fldr = ...

mpm = MapMatch(net=my_net, flag_name='ns-gps2sumo',
               export_html=True, export_geo_res=True,
               use_sub_net=True, time_unit='ms', dense_gps=False,
               gps_buffer=300, top_k=30,
               use_heading_inf=True, omitted_l=20,
               use_gps_source=False, gps_radius=6.0,
               out_fldr=os.path.join(fldr, 'output'))

match_res_df, warn_info, error_info = mpm.execute(gps_df=gps_df)
```

--------------------------------

### GoTrackIt Map Matching Initialization

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/案例介绍/匹配结果转微观仿真.md

This snippet initializes the GoTrackIt map matching process. It loads the previously generated road network shapefiles (`LinkAfterModify.shp`, `NodeAfterModify.shp`) into a `gotrackit.map.Net` object. The `Net` object is configured with parameters like `cut_off` and `is_hierarchical` before calling `init_net()` to prepare the network for matching.

```Python
import os
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import MapMatch

fldr = r'C:/Users/Administrator/Desktop/temp/gps2sumo/'

link_gdf = gpd.read_file(os.path.join(fldr, 'output', 'LinkAfterModify.shp'))
node_gdf = gpd.read_file(os.path.join(fldr, 'output','NodeAfterModify.shp'))

# 构建Net
my_net = Net(link_gdf=link_gdf, node_gdf=node_gdf, cut_off=600, is_hierarchical=True)
my_net.init_net()
```

--------------------------------

### Grid Parameter Search for Map Matching

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Demonstrates how to perform a grid search over map matching parameters (beta, gps_sigma, omitted_l, use_heading_inf) using the ParaGrid class. This helps find optimal parameter combinations by iterating through specified value lists and identifying combinations with minimal warnings.

```python
import pandas as pd
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import MapMatch
from gotrackit.model.Para import ParaGrid

if __name__ == '__main__':

    gps_df = gpd.read_file(r'./data/input/gps.geojson')

    # Please pay attention to the encoding of the shp file, you can specify the encoding to ensure that the fields are not garbled
    link = gpd.read_file(r'./data/input/modifiedConn_link.shp')
    node = gpd.read_file(r'./data/input/modifiedConn_node.shp')
    my_net = Net(link_gdf=link, node_gdf=node, 
                 fmm_cache=True, recalc_cache=False, fmm_cache_fldr=r'./data/input/net/xian')
    my_net.init_net()


    # 3. Create a new grid parameter object
    # Specify the list of values for parameters, you can specify lists for four parameters
    pgd = ParaGrid(use_heading_inf_list=[False, True], beta_list=[0.1, 1.0], gps_sigma_list=[1.0, 5.0])

    # 4. Match
    # Pass grid parameters: use_para_grid=True, para_grid=pgd
    mpm = MapMatch(net=my_net, flag_name='dense_example', 
                   use_sub_net=True, 
                   gps_buffer=400, top_k=20,
                   use_heading_inf=True, 
                   is_rolling_average=True, window=2,
                   dense_gps=True, dense_interval=50.0, 
                   export_html=True, use_gps_source=False,  gps_radius=6.0, 
                   export_geo_res=True, 
                   out_fldr=r'./data/output/match_visualization/dense_example',
                   use_para_grid=True, para_grid=pgd)
    res, warn_info, error_info = mpm.execute(gps_df=gps_df)

    res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)

    # You can view the number of warnings during the matching process for different parameter combinations
    print(pd.DataFrame(pgd.search_res))
```

--------------------------------

### 路网线层数据字段要求

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/数据要求.md

定义了路网线层文件的字段要求，包括路段唯一编码（link_id）、拓扑起点/终点（from_node, to_node）、通行方向（dir）、长度（length）、限速（speed）和路段几何（geometry）。强调link_id、from_node、to_node必须是大于0的正整数，dir为0、1或-1，geometry字段只允许LineString类型且不支持三维坐标。

```APIDOC
Road Network Link Schema:
  link_id: int
    - 必需字段，路段唯一编码, 一定是大于0的正整数。
  from_node: int
    - 必需字段，路段拓扑起点节点编号, 一定是大于0的正整数。
  to_node: int
    - 必需字段，路段拓扑终点节点编号, 一定是大于0的正整数。
  dir: int
    - 必需字段，路段通行方向，0或1或-1，0代表双向通行，1代表通行方向为路段拓扑正向，-1代表通行方向为路段拓扑反向。
  length: float
    - 必需字段，路段长度，单位米。
  speed: float
    - 非必需字段，路段限速，单位km/h，启用st-match时需要。
  geometry: geometry
    - 必需字段，路段几何线型。
    - 不允许出现MultiLineString类型，只允许LineString类型，不支持三维坐标。
```

--------------------------------

### Generate Warning Check Files

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Creates spatial bookmark (XML) and warning segment (SHP) files from map matching warnings. These files facilitate quick visual inspection and manual repair of road network connectivity issues in GIS software like QGIS.

```python
from gotrackit.MatchResAna import generate_check_file
if __name__ == '__main__':

    # After matching #
    match_res, warn_info, error_info = mpm.execute(gps_df=gps_df)

    # my_net is the net road network object
    generate_check_file(my_net, warn_info_dict=warn_info,
                        out_fldr=r'./data/output/match_visualization/0614BUG/',
                        file_name='check_net')
```

--------------------------------

### MapMatch.OnLineMapMatch Class Methods

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/Func&API/OnLineMapMatch.md

Documentation for the OnLineMapMatch class, which handles online map matching. It includes the constructor for initializing the map matching process and the execute method for performing the matching operation.

```APIDOC
OnLineMapMatch:
  __init__(self, ...)
    Initializes the OnLineMapMatch object.
    Parameters:
      (Details for parameters are not provided in the source text)
    Returns:
      An instance of OnLineMapMatch.

  execute(self, ...)
    Executes the online map matching algorithm.
    Parameters:
      (Details for parameters are not provided in the source text)
    Returns:
      (Details for return values are not provided in the source text)
```

--------------------------------

### Build Net Object

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Constructs a Net object, which represents the road network. This involves loading road link and node data from shapefiles, ensuring they are in the WGS-84 (EPSG:4326) coordinate system, and initializing the Net with a specified cut-off distance.

```python
# 构建一个net, 要求路网线层和路网点层必须是WGS-84, EPSG:4326 地理坐标系
# 请留意shp文件的编码，可以显示指定encoding，确保字段没有乱码
link = gpd.read_file(r'./data/input/net/xian/modifiedConn_link.shp')
node = gpd.read_file(r'./data/input/net/xian/modifiedConn_node.shp')
link = link.to_crs('EPSG:4326')  # 确保是EPSG:4326
node = node.to_crs('EPSG:4326')  # 确保是EPSG:4326
my_net = Net(link_gdf=link, node_gdf=node, cut_off=1200.0)
my_net.init_net()  # net初始化
```

--------------------------------

### Python: Map Matching with Projection Parameter Pre-calculation

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

This snippet enables projection parameter pre-calculation by setting `prj_cache=True` during Net initialization. This optimization can improve performance by caching projection-related computations. The map matching execution is standard.

```python
import geopandas as gpd
import pandas as pd
from trackit.core.network.network import Net
from trackit.core.map_match.map_match import MapMatch

link = gpd.read_file(r'./data/input/modifiedConn_link.shp')
node = gpd.read_file(r'./data/input/modifiedConn_node.shp')
my_net = Net(link_gdf=link, node_gdf=node, prj_cache=True)
my_net.init_net()  # net初始化

gps_df = pd.read_csv(r'./data/input/example_gps.csv')

mpm = MapMatch(net=my_net, flag_name='xa_sample', use_sub_net=True, 
               gps_buffer=100, top_k=20, dense_gps=False,
               use_heading_inf=True, omitted_l=6.0,
               del_dwell=True, dwell_l_length=50.0, dwell_n=0,
               export_html=True, export_geo_res=True, use_gps_source=True,
               gps_radius=15.0, export_all_agents=False,
               out_fldr=r'./data/output/match')
# execute函数返回三个结果:
# 第一个是匹配结果表、第二个是警告信息、第三个是错误信息
match_res, may_error_info, error_info = mpm.execute(gps_df=gps_df)
match_res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)
```

--------------------------------

### Path Matching with Trajectory Densification and Sub-network

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/快速开始/稀疏定位数据路径匹配.md

This Python code demonstrates path matching for sparse GPS data. It includes trajectory point densification using `TrajectoryPoints.dense()`, network initialization with `Net()`, and map matching execution via the `MapMatch` class. Key parameters like `gps_buffer`, `top_k`, and `dense_gps` are configured for sparse data scenarios. Dependencies include pandas, geopandas, and the gotrackit library.

```python
import pandas as pd
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import MapMatch
from gotrackit.gps.Trajectory import TrajectoryPoints

if __name__ == '__main__':
    # 读取GPS样例数据
    gps_df = pd.read_csv(r'./data/input/QuickStart-Match-1/example_sparse_gps.csv')

    # 利用gps数据构建TrajectoryPoints
    tp = TrajectoryPoints(gps_points_df=gps_df, plain_crs='EPSG:32649')
    tp.dense(dense_interval=120)  # 由于样例数据是稀疏定位数据，我们在匹配前进行增密处理
    gps_df = tp.trajectory_data(_type='df')
    tp.export_html(out_fldr=r'./data/output/match_visualization/QuickStart-Match-1')  # 输出增密前后的轨迹对比

    # 读取路网数据并且构建Net类、初始化
    link = gpd.read_file(r'./data/input/net/xian/modifiedConn_link.shp')
    node = gpd.read_file(r'./data/input/net/xian/modifiedConn_node.shp')
    my_net = Net(link_gdf=link, node_gdf=node, not_conn_cost=1200, cut_off=300)  # 默认的路径搜索截断距离为1200, 我们试一试减小到300
    my_net.init_net()  # net初始化

    # 由于轨迹点中大部分点是增密后的点，所以我们需要将gps_buffer调大才能确保轨迹点关联到路段
    # 由于我们已经提前将GPS数据进行增密，因此不需要使用MapMatch中的增密 - dense_gps=False
    mpm = MapMatch(net=my_net, use_sub_net=True, flag_name='sparse_sample',
                   time_format='%Y-%m-%d %H:%M:%S',
                   dense_gps=False,  # gps数据在预处理环节已经增密，这里不需要再打开增密选项
                   gps_buffer=700, top_k=20, 
                   use_heading_inf=True,
                   export_html=True, 
                   out_fldr=r'./data/output/match_visualization/QuickStart-Match-1',
                   gps_radius=15.0)

    # 执行匹配
    # 第一个返回结果是匹配结果表
    # 第二个是发生警告的agent的相关信息({agent_id1: pd.DataFrame(), agent_id2: pd.DataFrame()...})
    # 第三个是匹配出错的agent的id列表(GPS点经过预处理(或者原始数据)后点数量不足2个)
    match_res, warn_info, error_info = mpm.execute(gps_df=gps_df)
    match_res.to_csv(fr'./data/output/match_visualization/QuickStart-Match-1/sparse_match_res.csv',
                     encoding='utf_8_sig', index=False)
```

--------------------------------

### GPS Matching with Global Network (No Densification)

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/快速开始/稀疏定位数据路径匹配.md

Demonstrates GPS matching using the entire road network without creating a sub-network. This approach is effective when trajectory densification is not applied and a smaller GPS buffer is used. It utilizes `use_sub_net=False` and `dense_gps=False`.

```python
import pandas as pd
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import MapMatch
from gotrackit.gps.Trajectory import TrajectoryPoints

if __name__ == '__main__':
    # 读取GPS样例数据
    gps_df = pd.read_csv(r'./data/input/QuickStart-Match-1/example_sparse_gps.csv')
    
    # 注释掉该步骤的增密预处理
    # 利用gps数据构建TrajectoryPoints, 是否需要进行该步操作视实际情况而定
    # tp = TrajectoryPoints(gps_points_df=gps_df, plain_crs='EPSG:32649')
    # tp.dense(dense_interval=120)  # 由于样例数据是稀疏定位数据，我们在匹配前进行增密处理
    # gps_df = tp.trajectory_data(_type='df')
    # tp.export_html(out_fldr=r'./data/output/match_visualization/QuickStart-Match-1')  # 输出增密前后的轨迹对比

    # 读取路网数据并且构建Net类、初始化
    link = gpd.read_file(r'./data/input/net/xian/modifiedConn_link.shp')
    node = gpd.read_file(r'./data/input/net/xian/modifiedConn_node.shp')
    my_net = Net(link_gdf=link, node_gdf=node, not_conn_cost=1200, cut_off=1200)
    my_net.init_net()  # net初始化
    
    mpm = MapMatch(net=my_net, use_sub_net=False, flag_name='sparse_sample',
                   time_format='%Y-%m-%d %H:%M:%S',
                   dense_gps=False,  # 不打开增密选项
                   gps_buffer=100, top_k=20, 
                   use_heading_inf=True,
                   export_html=True, 
                   out_fldr=r'./data/output/match_visualization/QuickStart-Match-1',
                   gps_radius=15.0)

    # 执行匹配
    # 第一个返回结果是匹配结果表
    # 第二个是发生警告的agent的相关信息({agent_id1: pd.DataFrame(), agent_id2: pd.DataFrame()...})
    # 第三个是匹配出错的agent的id列表(GPS点经过预处理(或者原始数据)后点数量不足2个)
    match_res, warn_info, error_info = mpm.execute(gps_df=gps_df)
    match_res.to_csv(fr'./data/output/match_visualization/QuickStart-Match-1/sparse_match_res.csv',
                     encoding='utf_8_sig', index=False)

```

--------------------------------

### Python: Map Matching with Path Pre-calculation

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

This snippet enables path pre-calculation by setting `fmm_cache=True` and specifying a cache folder for the Net initialization. This can speed up subsequent operations by caching computed paths. The rest of the map matching process remains similar to the standard approach.

```python
import geopandas as gpd
import pandas as pd
from trackit.core.network.network import Net
from trackit.core.map_match.map_match import MapMatch

link = gpd.read_file(r'./data/input/modifiedConn_link.shp')
node = gpd.read_file(r'./data/input/modifiedConn_node.shp')
my_net = Net(link_gdf=link, node_gdf=node, 
                 fmm_cache=True, fmm_cache_fldr=r'./data/input/', recalc_cache=False)
my_net.init_net()  # net初始化

gps_df = pd.read_csv(r'./data/input/example_gps.csv')

mpm = MapMatch(net=my_net, flag_name='xa_sample', use_sub_net=True, 
               gps_buffer=100, top_k=20, dense_gps=False,
               use_heading_inf=True, omitted_l=6.0,
               del_dwell=True, dwell_l_length=50.0, dwell_n=0,
               export_html=True, export_geo_res=True, use_gps_source=True,
               gps_radius=15.0, export_all_agents=False,
               out_fldr=r'./data/output/match')
# execute函数返回三个结果:
# 第一个是匹配结果表、第二个是警告信息、第三个是错误信息
match_res, may_error_info, error_info = mpm.execute(gps_df=gps_df)
match_res.to_csv(r'./data/output/match_res.csv', encoding='utf_8_sig', index=False)
```

--------------------------------

### 实时地图匹配接口示例

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/实时路径匹配.md

展示如何使用OnLineMapMatch类的execute方法进行实时地图匹配。该示例涉及网络初始化、GPS数据通过卡尔曼滤波器平滑，以及最终的地图匹配操作。

```Python
# 1. 从gotrackit导入相关模块
import pandas as pd
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import OnLineMapMatch
from gotrackit.tools.kf import OnLineTrajectoryKF

# 这是一个接入实时GPS数据的示例函数，用户需要自己依据实际情况去实现它
def monitor_rt_gps(once_num: int = 2):
    loc_df = pd.read_csv(r'./gps.csv')
    num = len(loc_df)
    loc_df.reset_index(inplace=True, drop=True)
    i = 0
    while i < num:
        yield loc_df.loc[i: i + once_num - 1, :].copy()
        i += once_num

if __name__ == '__main__':

    link = gpd.read_file('Link.shp')
    node = gpd.read_file('Node.shp')
    my_net = Net(link_gdf=link, node_gdf=node)
    my_net.init_net()

    # 新建一个实时匹配类别
    ol_mpm = OnLineMapMatch(net=my_net, gps_buffer=50,
                            out_fldr=r'./data/output/match_visualization/real_time/')

    # 新建一个实时卡尔曼滤波器
    ol_kf = OnLineTrajectoryKF()

    c = 0
    for rt_gps_df in monitor_rt_gps(once_num=2):
        if rt_gps_df.empty:
            continue
        ol_mpm.flag_name = rf'real_time_{c}'

        # 更新当前时刻接收到的定位数据
        ol_kf.renew_trajectory(trajectory_df=rt_gps_df)

        # 滤波平滑
        gps_df = ol_kf.kf_smooth(p_deviation=0.002)

        # 实时匹配
        res, warn_info, error_info = ol_mpm.execute(gps_df=gps_df,  overlapping_window=3)

```

--------------------------------

### Import Gotrackit Modules

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/UserGuide/路径匹配.md

Imports essential Python libraries including pandas for data manipulation, geopandas for geospatial data handling, and specific components (Net, MapMatch) from the gotrackit library required for path matching operations.

```python
import pandas as pd
import geopandas as gpd
from gotrackit.map.Net import Net
from gotrackit.MapMatch import MapMatch
```

--------------------------------

### 设置MapMatch参数并执行匹配

Source: https://github.com/zdsjjttlg/trackit/blob/main/docs/快速开始/非稀疏定位数据路径匹配.md

配置MapMatch类的参数，包括网络对象、时间格式、GPS缓冲区大小、是否使用航向信息等，然后调用execute方法执行地图匹配。该方法返回匹配结果、警告信息和错误信息。

```python
from gotrackit.MapMatch import MapMatch
# 构建匹配类
# 指定要输出HTML可视化文件
# 指定项目的标志字符flag_name='general_sample', 这个用户可以自定义
# gps数据时间列的值都是形如2022-05-12 16:27:46，因此指定时间列格式为 '%Y-%m-%d %H:%M:%S'
# 关于gps_buffer的确定，需要将路网和gps数据一同使用gis软件可视化，大概确定GPS数据和候选路段的距离
mpm = MapMatch(net=my_net, flag_name='general_sample', 
               time_format='%Y-%m-%d %H:%M:%S',
               gps_buffer=120, 
               use_heading_inf=True, omitted_l=6.0, 
               del_dwell=False, dense_gps=False,
               export_html=True, 
               out_fldr=r'./data/output/match_visualization/QuickStart-Match-1')

# 执行匹配
# 第一个返回结果是匹配结果表
# 第二个是发生警告的agent的相关信息({agent_id1: pd.DataFrame(), agent_id2: pd.DataFrame()...})
# 第三个是匹配出错的agent的id列表(GPS点经过预处理(或者原始数据)后点数量不足2个)
match_res, warn_info, error_info = mpm.execute(gps_df=gps_df)
match_res.to_csv(fr'./data/output/match_visualization/QuickStart-Match-1/general_match_res.csv',
                 encoding='utf_8_sig', index=False)
```

--------------------------------

### Upgrade gotrackit Package

Source: https://github.com/zdsjjttlg/trackit/blob/main/README_EN.md

Upgrades the gotrackit package to the latest version from PyPI using the specified index URL.

```shell
pip install --upgrade  -i https://pypi.org/simple/ gotrackit
```