# 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` |