|
| 1 | +# OpenMVS Copilot Instructions |
| 2 | + |
| 3 | +OpenMVS is a multi-view stereo reconstruction library implementing a complete photogrammetry pipeline from camera poses + sparse point-cloud to textured mesh. The codebase is mature C++ with custom framework patterns. |
| 4 | + |
| 5 | +## Project Architecture |
| 6 | + |
| 7 | +### Core Namespaces & Structure |
| 8 | +- **MVS namespace**: Core reconstruction algorithms (`libs/MVS/`) |
| 9 | +- **VIEWER namespace**: 3D visualization application (`apps/Viewer/`) |
| 10 | +- **SEACAVE namespace**: Low-level utilities (`libs/Common/`) |
| 11 | + |
| 12 | +### Key Libraries (libs/) |
| 13 | +- `Common/`: Custom framework (types, logging, containers, math utilities) |
| 14 | +- `MVS/`: Core MVS algorithms (Scene, Image, Camera, Mesh, PointCloud, etc.) |
| 15 | +- `IO/`: File format support (PLY, OBJ, MVS formats) |
| 16 | +- `Math/`: Mathematical primitives and operations |
| 17 | + |
| 18 | +### Applications (apps/) |
| 19 | +Each app is a standalone executable for specific pipeline stages: |
| 20 | +- `DensifyPointCloud`: Dense reconstruction from sparse points |
| 21 | +- `ReconstructMesh`: Surface reconstruction from dense points |
| 22 | +- `RefineMesh`: Mesh quality improvement |
| 23 | +- `TextureMesh`: Apply textures to meshes |
| 24 | +- `Viewer`: Interactive 3D visualization with OpenGL |
| 25 | +- `Interface*`: Import/export to other pipelines (COLMAP, OpenMVG, etc.) |
| 26 | + |
| 27 | +## Build System & Workflows |
| 28 | + |
| 29 | +### Building |
| 30 | +```bash |
| 31 | +# Standard build (uses vcpkg for dependencies) |
| 32 | +mkdir make && cd make |
| 33 | +cmake .. |
| 34 | +cmake --build . -j4 # or ninja (generates ninja files) |
| 35 | +``` |
| 36 | + |
| 37 | +### Key Build Tools |
| 38 | +- **vcpkg**: Automatic dependency management (see `vcpkg.json`) |
| 39 | +- **CMake**: Primary build system with custom utilities in `build/Utils.cmake` |
| 40 | +- **ninja**: Preferred generator (faster than make) |
| 41 | + |
| 42 | +### Development Builds |
| 43 | +- Debug builds in `make/bin/Debug/` |
| 44 | +- Built executables: `./bin/Debug/Viewer`, `./bin/Debug/DensifyPointCloud`, etc. |
| 45 | +- Use `cmake --build . -j4` from `make/` directory for incremental builds |
| 46 | + |
| 47 | +## Code Patterns & Conventions |
| 48 | + |
| 49 | +### Memory Management |
| 50 | +- Reference counting with automatic cleanup |
| 51 | +- RAII patterns throughout |
| 52 | + |
| 53 | +### Logging & Debugging |
| 54 | +```cpp |
| 55 | +DEBUG("Message"); // Level 0 (always shown in debug) |
| 56 | +DEBUG_EXTRA("Details"); // Level 1 (verbose) |
| 57 | +VERBOSE("Info: %s", str); // General logging |
| 58 | +``` |
| 59 | +
|
| 60 | +### Error Handling |
| 61 | +- `ASSERT(condition)` for debug checks |
| 62 | +- Return false/NULL for failures |
| 63 | +
|
| 64 | +### Common Typedefs |
| 65 | +```cpp |
| 66 | +typedef SEACAVE::Point3f Point3f; // 3D points |
| 67 | +typedef SEACAVE::String String; // String type |
| 68 | +#define NO_ID ((uint32_t)-1) // Invalid index |
| 69 | +``` |
| 70 | +Most of OpenMVS code uses custom point and matrix types derived from OpenCV types, e.g., `SEACAVE::Point3f`, `SEACAVE::Matrix4f`. Hoewever, some components use Eigen3 types, e.g. `SEACAVE::AABB3d` and `SEACAVE::Ray3d` classes. There custom types support convertion operation to and from Eigen3 types. |
| 71 | + |
| 72 | +SEACAVE::cList template class is a custom vector implementation used throughout the codebase, fully compatible with std::vector. It provides additional functionality such as using or not the constructor for the elements, custom size type, and additional operations like GetMean, GetMedian, Sort, etc. |
| 73 | + |
| 74 | +Often used is also FOREACH macro for iterating over any vector-like container: |
| 75 | +```cpp |
| 76 | +FOREACH(index, container) { |
| 77 | + auto& element = container[index]; |
| 78 | + // Do something with element |
| 79 | +} |
| 80 | +``` |
| 81 | +Similarly, RFOREACH macro iterates in reverse order. |
| 82 | +
|
| 83 | +TD_TIMER_START() and TD_TIMER_GET_FMT() macros are used for performance measurements. TD_TIMER_START() (similarly TD_TIMER_STARTD() paird with DEBUG() prints) starts a timer, and TD_TIMER_GET_FMT() returns a formatted string with the elapsed time since the timer was started. |
| 84 | +
|
| 85 | +VERBOSE() macro is used for general logging messages. It works similarly to DEBUG() macro, but is intended for critical information, as it always prints regardless of debug level. DEBUG_EXTRA() and DEBUG_ULTIMATE() macros are used for more verbose logging, with DEBUG_ULTIMATE() being the most verbose. |
| 86 | +
|
| 87 | +### Configuration |
| 88 | +- Build-time config in `ConfigLocal.h` (generated) |
| 89 | +- Runtime options via boost::program_options pattern |
| 90 | +- Feature flags like `OpenMVS_USE_CUDA`, `OpenMVS_USE_CERES` |
| 91 | +- Each library uses a precompiled header (`Common.h`) for common includes, like Eigen, OpenCV, etc. |
| 92 | +
|
| 93 | +## Viewer Application Specifics |
| 94 | +
|
| 95 | +### Key Classes |
| 96 | +- `Scene`: Main data container (MVS::Scene + rendering state) |
| 97 | +- `Window`: GLFW window management + input handling |
| 98 | +- `Renderer`: OpenGL rendering (points, meshes, cameras) |
| 99 | +- `Camera`: View/projection matrices + navigation |
| 100 | +- `UI`: ImGui interface components |
| 101 | +
|
| 102 | +### Rendering Pipeline |
| 103 | +```cpp |
| 104 | +window.Run(scene) → |
| 105 | + Render(scene) → |
| 106 | + renderer->RenderPointCloud/RenderMesh → |
| 107 | + OpenGL draw calls |
| 108 | +``` |
| 109 | + |
| 110 | +### Event System |
| 111 | +- GLFW events → Window callbacks → Control system updates |
| 112 | +- Render-only-on-change optimization uses `glfwWaitEventsTimeout()` |
| 113 | +- `Window::RequestRedraw()` triggers frame updates |
| 114 | + |
| 115 | +## Integration Points |
| 116 | + |
| 117 | +### File Formats |
| 118 | +- `.mvs`: Native binary format (boost serialization) |
| 119 | +- `.ply`: Point clouds and meshes (ASCII/binary) |
| 120 | +- `.obj`: Mesh export with MTL materials |
| 121 | +- Interface apps handle external formats (COLMAP, etc.) |
| 122 | + |
| 123 | +### External Dependencies |
| 124 | +- **Eigen3**: Linear algebra (matrices, vectors) |
| 125 | +- **OpenCV**: Image processing and I/O |
| 126 | +- **CGAL**: Computational geometry |
| 127 | +- **Boost**: Serialization, program options, containers |
| 128 | +- **CUDA**: GPU acceleration (optional) |
| 129 | +- **GLFW/OpenGL**: Viewer rendering |
| 130 | + |
| 131 | +### Cross-Component Communication |
| 132 | +- `MVS::Scene` is the central data exchange format |
| 133 | +- Applications typically: load scene → process → save scene |
| 134 | +- Viewer loads and visualizes any stage of the pipeline |
| 135 | + |
| 136 | +## Testing & Debugging |
| 137 | + |
| 138 | +### Running Tests |
| 139 | +```bash |
| 140 | +# From make/ directory |
| 141 | +ctest # Run all tests |
| 142 | +./bin/Debug/Tests # Direct test executable |
| 143 | +``` |
| 144 | + |
| 145 | +### Common Debugging |
| 146 | +- Use `DEBUG()` macros liberally |
| 147 | +- Check `ASSERT()` failures for logic errors |
| 148 | +- Viewer: Use F1 for help dialog, check console output |
| 149 | +- Memory issues: Build with `_DEBUG` for additional checks |
| 150 | + |
| 151 | +## Performance Considerations |
| 152 | + |
| 153 | +- Multi-threading via OpenMP (`#pragma omp parallel`) |
| 154 | +- CUDA kernels for GPU acceleration (when enabled) |
| 155 | +- Memory-mapped files for large datasets |
| 156 | +- Spatial data structures (octrees) for efficient queries |
| 157 | +- Viewer optimizations: frustum culling, render-only-on-change mode |
0 commit comments