153 lines
4.1 KiB
Markdown
153 lines
4.1 KiB
Markdown
# TrackEngine
|
|
|
|
A C++17 route-matching engine built on [OSRM](https://github.com/Project-OSRM/osrm-backend), consuming GPS CSV streams via stdin and producing matched results.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
| Requirement | Notes |
|
|
|---|---|
|
|
| **Windows 10/11 (x64)** | MSVC toolchain only |
|
|
| **Visual Studio 2019 or 2022** | With the "Desktop development with C++" workload |
|
|
| **OSRM** | Installed to `C:\OSRM\` (headers + libs) |
|
|
| **OSRM backend clone** | At `C:\Users\TRIZ\clones\osrm-backend\` (vcpkg deps + third-party headers) |
|
|
| **nmake** | Ships with Visual Studio — run everything inside a *Developer Command Prompt* |
|
|
|
|
---
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
trackengine/
|
|
├── src/
|
|
│ └── main.cpp
|
|
├── kdtree/
|
|
│ └── kdtree.c
|
|
├── tomlcpp/
|
|
│ ├── tomlcpp.cpp
|
|
│ └── toml.c
|
|
├── data/ ← OSRM map data, config, etc.
|
|
├── bin/ ← created automatically at build time
|
|
├── Makefile
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## Building
|
|
|
|
### 1 — Open a Developer Command Prompt
|
|
|
|
Start → **"Developer Command Prompt for VS 20xx"**
|
|
*(or run `vcvars64.bat` inside any terminal to activate the MSVC environment.)*
|
|
|
|
### 2 — Navigate to the project root
|
|
|
|
```cmd
|
|
cd C:\Users\TRIZ\clones\tracluster
|
|
```
|
|
|
|
### 3 — Compile
|
|
|
|
```cmd
|
|
nmake /f Makefile
|
|
```
|
|
|
|
This will:
|
|
|
|
- Compile `src/main.cpp`, `kdtree/kdtree.c`, `tomlcpp/tomlcpp.cpp`, and `tomlcpp/toml.c` with `/std:c++17 /O3 /MD`.
|
|
- Link against `C:\OSRM\lib\osrm.lib`, all vcpkg `.lib` files, and `AdvAPI32.lib`.
|
|
- Output the executable to **`bin\trackengine.exe`**.
|
|
|
|
### 4 — Run (quick test)
|
|
|
|
The `all` target automatically pipes a sample CSV through the engine after building:
|
|
|
|
```cmd
|
|
type C:\Users\TRIZ\clones\tracluster\gps_260205_070000.csv | bin\trackengine.exe
|
|
```
|
|
|
|
To run it manually at any time:
|
|
|
|
```cmd
|
|
type path\to\your_gps_file.csv | bin\trackengine.exe
|
|
```
|
|
|
|
### Cleaning build artefacts
|
|
|
|
```cmd
|
|
nmake /f Makefile clean
|
|
```
|
|
|
|
---
|
|
|
|
## Packaging for deployment
|
|
|
|
After a successful build, bundle **`bin\`** and **`data\`** together into split 100 MB ZIP archives using 7-Zip:
|
|
|
|
```cmd
|
|
"C:\Program Files\7-Zip\7z.exe" a -tzip -v100m TrackEngine.zip bin\ data\
|
|
```
|
|
|
|
This produces a sequence of files such as:
|
|
|
|
```
|
|
TrackEngine.zip.001
|
|
TrackEngine.zip.002
|
|
TrackEngine.zip.003
|
|
...
|
|
```
|
|
|
|
> **Tip — 7-Zip not installed?**
|
|
> Download it from <https://www.7-zip.org/> and add its folder to your `PATH`, or use the full path shown above.
|
|
|
|
---
|
|
|
|
## Uploading to cPanel
|
|
|
|
1. Log in to your cPanel account and open **File Manager**.
|
|
2. Navigate to:
|
|
```
|
|
public_html → files → TrackEngine
|
|
```
|
|
3. Upload each `TrackEngine.zip.001`, `TrackEngine.zip.002`, … part — choose **Overwrite** if prompted for existing files.
|
|
4. Once all parts are uploaded, verify the file list matches what was produced locally.
|
|
|
|
---
|
|
|
|
## Restarting Tomcat
|
|
|
|
After uploading, restart the Tomcat server so the web application picks up the new binaries:
|
|
|
|
- In cPanel look for **Tomcat Manager** (or use the **Application Manager** if your host uses JVM hosting).
|
|
- Click **Stop** → wait a moment → click **Start**.
|
|
- Alternatively, if you have SSH access:
|
|
```bash
|
|
/path/to/tomcat/bin/shutdown.sh && /path/to/tomcat/bin/startup.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Enabling the TrackEngine integration
|
|
|
|
Open your web application's configuration file (e.g. `application.properties` or `config.toml`) and confirm the following property is set to `true`:
|
|
|
|
```properties
|
|
trizdistribution.trackEngine.enabled=true
|
|
```
|
|
|
|
After saving the file and restarting Tomcat (see above), the web application will automatically detect, download, and activate the newly uploaded TrackEngine binaries.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely cause | Fix |
|
|
|---|---|---|
|
|
| `cl` not found | Wrong terminal | Use Developer Command Prompt |
|
|
| Linker error on `osrm.lib` | Wrong OSRM install path | Verify `C:\OSRM\lib\osrm.lib` exists |
|
|
| vcpkg `.lib` wildcard fails | nmake doesn't expand `*.lib` | List each `.lib` explicitly in `LIBS` |
|
|
| Engine exits silently | Missing `data/` files | Ensure OSRM `.osrm` processed map files are in `data/` |
|
|
| Web app doesn't start engine | Property not set | Double-check `trizdistribution.trackEngine.enabled=true` |
|