TrackEngine/README.md

TrackEngine

A C++17 route-matching engine built on OSRM, 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

cd C:\Users\TRIZ\clones\tracluster

3 — Compile

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:

type C:\Users\TRIZ\clones\tracluster\gps_260205_070000.csv | bin\trackengine.exe

To run it manually at any time:

type path\to\your_gps_file.csv | bin\trackengine.exe

Cleaning build artefacts

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:

"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:

  /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:

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