Track3d - the 3D tracking from 3D-PTV by ETH Zurich

.gitignore

@@ -30,3 +30,4 @@ py_bind/wheelhouse/*
 build_artifacts
 # conda smithy ci-skeleton end
 *.whl
+py_bind/optv/optv/*.h

docs/readme_debugging.md

@@ -0,0 +1,162 @@
+# OpenPTV liboptv Developer README
+
+## Overview
+
+This library (`liboptv`) is part of the OpenPTV project and provides core algorithms for particle tracking velocimetry, including 2D and 3D tracking routines. The codebase is C99, uses CMake for building, and includes a comprehensive suite of unit tests using the [Check](https://libcheck.github.io/check/) framework.
+
+This README is for developers who want to **debug**, **extend**, or **test** the library, especially using Visual Studio Code (VS Code) or other modern IDEs.
+
+---
+
+## Prerequisites
+
+- **Linux** (tested on Ubuntu)
+- **CMake** (>=3.10)
+- **GCC** (with gdb for debugging)
+- **Check** unit testing framework (`libcheck-dev`)
+- **VS Code** (recommended, with C/C++ extension)
+- **Electric Fence** (`electric-fence`, optional, for memory debugging)
+
+Install dependencies (Ubuntu example):
+
+```bash
+sudo apt-get update
+sudo apt-get install build-essential cmake libcheck-dev electric-fence gdb
+```
+
+---
+
+## Building the Library
+
+```bash
+cd /path/to/openptv/liboptv
+mkdir -p build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Debug ..
+make
+```
+
+- The default build type is **Debug** (with debug symbols, no optimization).
+- The shared library will be built as `liboptv.so` in `build/src/`.
+
+---
+
+## Running Tests
+
+To run all tests:
+
+```bash
+make verify
+```
+
+Or, using CTest:
+
+```bash
+cd build
+ctest
+```
+
+To run a specific test (e.g., only 3D tracking):
+
+```bash
+ctest -R track3d
+```
+
+To see output on failure:
+
+```bash
+CTEST_OUTPUT_ON_FAILURE=1 ctest -V -R track3d
+```
+
+---
+
+## Debugging with VS Code
+
+1. **Open the project root in VS Code:**
+
+    ```bash
+    code /path/to/openptv/liboptv
+    ```
+
+2. **Build in Debug mode** (see above).
+
+3. **Set up `.vscode/launch.json`:**
+
+    Example for debugging the 3D tracking test:
+
+    ```json
+    {
+      "version": "0.2.0",
+      "configurations": [
+        {
+          "name": "Debug check_track3d",
+          "type": "cppdbg",
+          "request": "launch",
+          "program": "${workspaceFolder}/build/tests/check_track3d",
+          "args": [],
+          "stopAtEntry": false,
+          "cwd": "${workspaceFolder}/build/tests",
+          "environment": [],
+          "externalConsole": false,
+          "MIMode": "gdb",
+          "setupCommands": [
+            {
+              "description": "Enable pretty-printing for gdb",
+              "text": "-enable-pretty-printing",
+              "ignoreFailures": true
+            }
+          ]
+        }
+      ]
+    }
+    ```
+
+4. **Set breakpoints** in any source file (e.g., `src/track3d.c`).
+
+5. **Start debugging** from the Run & Debug panel.
+
+---
+
+## Tips for Debugging
+
+- **Step into library code:** Ensure you build with `-g -O0` (Debug mode, no optimization).
+- **Flush output:** Add `fflush(stdout);` after `printf` to see output immediately during tests.
+- **Run a single test:** Use `ctest -R testname` or pass arguments to your test executable.
+- **Check source paths:** Open the original source files in VS Code for breakpoints to work.
+
+---
+
+## Directory Structure
+
+- `src/` — Core library source files
+- `include/` — Public headers
+- `tests/` — Unit and integration tests (Check framework)
+- `build/` — Build directory (created by you)
+- `.vscode/` — VS Code configuration (optional)
+
+---
+
+## Common Issues
+
+- **Cannot step into src code:**  
+  Make sure you built with debug symbols and no optimization. Clean and rebuild if needed.
+- **Linker errors for efence:**  
+  Install `electric-fence` or comment out its usage in `CMakeLists.txt`.
+- **CTest output is buffered:**  
+  Use `fflush(stdout);` or run with `CTEST_OUTPUT_ON_FAILURE=1`.
+
+---
+
+## Contributing
+
+- Follow the code style of existing files.
+- Add tests for new features or bugfixes.
+- Document your changes.
+
+---
+
+## Further Help
+
+If you have questions or issues, open an issue on the OpenPTV GitHub or contact the maintainers.
+
+---

liboptv/include/correspondences.h

@@ -8,7 +8,7 @@
 #include "calibration.h"
 #include "epi.h"
 
-#define nmax 202400
+#define nmax 20240
 
 
 typedef struct

liboptv/include/track3d.h

@@ -0,0 +1,18 @@
+#ifndef TRACK3D_H
+#define TRACK3D_H
+
+#include "parameters.h"
+#include "vec_utils.h"
+#include "imgcoord.h"
+#include "multimed.h"
+#include "orientation.h"
+#include "calibration.h"
+#include "track.h"
+#include "tracking_frame_buf.h"
+
+
+void track3d_loop(tracking_run *run_info, int step);
+int find_candidates_in_3d(frame *frm, vec3d pos, double dx, double dy, double dz, int *indices, int max_cands);
+
+
+#endif // TRACK3D_H

liboptv/src/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # Turn on more warnings
 if(MSVC)
   # Force to always compile with W4
@@ -14,8 +13,7 @@ endif()
 
 include_directories("../include/")
 
-add_library (optv SHARED tracking_frame_buf.c calibration.c parameters.c lsqadj.c ray_tracing.c trafo.c vec_utils.c image_processing.c multimed.c imgcoord.c epi.c orientation.c sortgrid.c segmentation.c correspondences.c track.c tracking_run.c)
-
+add_library (optv SHARED tracking_frame_buf.c calibration.c parameters.c lsqadj.c ray_tracing.c trafo.c vec_utils.c image_processing.c multimed.c imgcoord.c epi.c orientation.c sortgrid.c segmentation.c correspondences.c track.c tracking_run.c track3d.c)
 
 
 if(UNIX)
@@ -31,3 +29,8 @@ if(WIN32)
 endif(WIN32)
 
 install(TARGETS optv DESTINATION lib)
+
+# Set Debug as the default build type if not specified
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Debug CACHE STRING "Choose the type of build." FORCE)
+endif()