Add README.md documentation to all AliceVision modules

src/aliceVision/calibration/README.md

@@ -0,0 +1,49 @@
+# calibration
+
+This module provides tools for camera calibration, including checkerboard detection and lens distortion estimation.
+
+## Checker Detection
+
+The `CheckerDetector` class detects checkerboard patterns in images. It supports:
+
+- Heavily distorted images
+- Blurred images
+- Partially occluded checkerboards (even occluded at the center)
+- Checkerboards without size information
+- Simple and nested grids (when centered on the image center)
+
+A checkerboard corner is described by:
+- Its center position
+- Its two principal dimensions
+- A scale of detection (higher scale means better detection quality)
+
+The detection is based on the following references: [ROCHADE], [Geiger], [Chen], [Liu], [Abdulrahman], [Bok].
+
+```cpp
+aliceVision::calibration::CheckerDetector detector;
+// detect checkerboard corners in an image
+detector.process(image);
+// retrieve detected corners and boards
+const auto& corners = detector.getCorners();
+const auto& boards = detector.getBoards();
+```
+
+## Distortion Estimation
+
+Several methods are provided to estimate lens distortion from calibration data:
+
+- `distortionEstimationGeometry`: estimates distortion from geometric constraints
+- `distortionEstimationLine`: estimates distortion from lines in the scene
+- `distortionEstimationPoint`: estimates distortion from point correspondences
+
+Each method produces a `Statistics` struct describing the quality of the estimation:
+
+```cpp
+struct Statistics {
+    double mean;
+    double stddev;
+    double median;
+    double lastDecile;
+    double max;
+};
+```

src/aliceVision/cmdline/README.md

@@ -0,0 +1,39 @@
+# cmdline
+
+This module provides utilities for building command-line applications in AliceVision.
+
+It includes macros and helper functions to simplify the setup of command-line tools with consistent error handling, logging, and option validation.
+
+## Macros
+
+### `ALICEVISION_COMMANDLINE_START` / `ALICEVISION_COMMANDLINE_END`
+
+These macros wrap the main body of a command-line tool, providing:
+
+- Automatic timing of the command execution
+- Consistent error handling for `std::exception` and unknown exceptions
+- Standardized success and failure return codes
+
+```cpp
+int main(int argc, char** argv)
+{
+    ALICEVISION_COMMANDLINE_START
+
+    // ... parse options and run the algorithm ...
+
+    ALICEVISION_COMMANDLINE_END
+}
+```
+
+## Option Validation
+
+The `optInRange<T>(min, max, opt_name)` helper returns a validation function that checks whether a command-line option value falls within a specified range. It integrates with Boost.Program_options:
+
+```cpp
+po::options_description params("Parameters");
+params.add_options()
+    ("threshold", po::value<float>()->notifier(aliceVision::optInRange(0.f, 1.f, "threshold")),
+     "Threshold value in [0, 1].");
+```
+
+If the value is outside the range, a `boost::program_options::validation_error` is thrown with an appropriate message.

src/aliceVision/colorHarmonization/README.md

@@ -0,0 +1,38 @@
+# colorHarmonization
+
+This module provides tools for color harmonization across a set of images. It adjusts the color/gain of images so that overlapping regions share a consistent appearance.
+
+## Overview
+
+Color harmonization is the process of making color-related properties (gain, offset) consistent across a set of images that share common content. This is particularly important in photogrammetry pipelines where many overlapping images are combined.
+
+The approach is based on L∞ optimization of pairwise color histogram differences across an image graph, as described in:
+
+> [1] P. Moulon, P. Monasse, R. Marlet. *Adaptive Structure from Motion with a Contrario Model Estimation.* ACCV 2012.
+
+## Common Data Strategies
+
+The module defines a base class `CommonDataByPair` and three concrete strategies for computing the overlapping regions (masks) between image pairs:
+
+- `CommonDataByPair_fullFrame`: uses the entire image frame as the overlap mask
+- `CommonDataByPair_matchedPoints`: uses matched feature points to define the region of interest
+- `CommonDataByPair_vldSegment`: uses VLD (Virtual Line Descriptor) segments to define the overlap region
+
+```cpp
+// Example: using matched points to compute color histograms
+std::unique_ptr<CommonDataByPair> dataProvider =
+    std::make_unique<CommonDataByPair_matchedPoints>(leftImagePath, rightImagePath, matches);
+
+image::Image<unsigned char> maskLeft, maskRight;
+dataProvider->computeMask(maskLeft, maskRight);
+```
+
+## Gain/Offset Constraint Builder
+
+The `GainOffsetConstraintBuilder` class builds a linear program that enforces consistent gain and offset parameters across image pairs, minimizing the L∞ norm of histogram alignment errors.
+
+## API
+
+- `CommonDataByPair::computeMask(maskLeft, maskRight)` — Compute binary masks for the two images.
+- `CommonDataByPair::computeHisto(histo, mask, channelIndex, image)` — Compute a color histogram for the masked region of an image channel.
+- `GainOffsetConstraintBuilder` — Build linear constraints for gain/offset optimization.

src/aliceVision/dataio/README.md

@@ -0,0 +1,52 @@
+# dataio
+
+This module provides a feed-based interface for reading image data from various sources (image sequences, videos, and E57 point cloud files) in a unified way.
+
+## Overview
+
+The `dataio` module abstracts the input source of images so that downstream algorithms can work with any of the supported media types without modification.
+
+## Feed Interface
+
+The `IFeed` abstract base class defines the interface for all data feeds:
+
+```cpp
+class IFeed {
+public:
+    virtual bool isInit() const = 0;
+    virtual bool readImage(image::Image<image::RGBColor>& imageRGB,
+                           camera::Pinhole& camIntrinsics,
+                           std::string& mediaPath,
+                           bool& hasIntrinsics) = 0;
+    virtual std::size_t nbFrames() const = 0;
+    virtual bool goToFrame(const unsigned int frame) = 0;
+    virtual bool goToNextFrame() = 0;
+};
+```
+
+## Feed Provider
+
+The `FeedProvider` class is the main entry point. It automatically detects the input type and creates the appropriate feed:
+
+```cpp
+// Create a feed from any supported source (image, video, sfmData, ...)
+aliceVision::dataio::FeedProvider feed("/path/to/images_or_video");
+
+image::Image<image::RGBColor> image;
+camera::Pinhole camIntrinsics;
+std::string mediaPath;
+bool hasIntrinsics;
+
+while (feed.readImage(image, camIntrinsics, mediaPath, hasIntrinsics))
+{
+    // process image ...
+    feed.goToNextFrame();
+}
+```
+
+## Supported Feed Types
+
+- **`ImageFeed`**: reads from a single image file or a directory of image files
+- **`VideoFeed`**: reads frames from a video file
+- **`SfMDataFeed`**: reads images referenced in an SfMData file
+- **`E57Reader`**: reads point cloud data from E57 files

src/aliceVision/depthMap/README.md

@@ -0,0 +1,49 @@
+# depthMap
+
+This module provides GPU-accelerated depth map estimation from multi-view stereo images.
+
+## Overview
+
+The `depthMap` module computes per-camera depth maps using a two-stage pipeline:
+
+1. **SGM (Semi-Global Matching)**: An efficient global stereo matching algorithm that propagates local matching costs along multiple 1-D paths in the image.
+2. **Refine**: A local refinement step that improves depth precision sub-pixel accuracy.
+
+Both stages run on the GPU (CUDA) and support large images through a tiling strategy.
+
+## Pipeline
+
+### Semi-Global Matching (SGM)
+
+The `Sgm` class implements the Semi-Global Matching algorithm:
+
+- Builds a cost volume from patch-based similarity between the reference camera and target cameras
+- Propagates costs along multiple directions in the image
+- Selects the best depth hypothesis per pixel
+
+### Refine
+
+The `Refine` class refines the depth estimates produced by SGM:
+
+- Uses local optimization around the SGM depth estimate
+- Achieves sub-pixel precision
+
+### Normal Map Estimation
+
+The `NormalMapEstimator` class estimates a surface normal map from the computed depth map.
+
+## Tiling
+
+For large images, computation is split into tiles that fit in GPU memory. The `DepthMapEstimator` manages the tiling and multi-GPU execution:
+
+```cpp
+DepthMapEstimator estimator(mp, tileParams, depthMapParams, sgmParams, refineParams);
+estimator.compute(cudaDeviceId, cams);
+```
+
+## Parameters
+
+- `DepthMapParams`: high-level parameters (number of target cameras, tiling options, patch pattern)
+- `SgmParams`: Semi-Global Matching parameters (number of depth samples, similarity threshold, ...)
+- `RefineParams`: Refine step parameters (number of iterations, patch size, ...)
+- `TileParams`: tile size and overlap parameters

src/aliceVision/featureEngine/README.md

@@ -0,0 +1,36 @@
+# featureEngine
+
+This module provides the high-level orchestration of feature extraction across all views in an SfMData scene.
+
+## Overview
+
+The `featureEngine` module manages the extraction of local features (keypoints and descriptors) for each image in the dataset. It handles:
+
+- CPU and GPU image describers
+- Memory management and scheduling
+- Output of feature (`.feat`) and descriptor (`.desc`) files
+
+## FeatureExtractor
+
+The `FeatureExtractor` class is the main entry point. It takes an `SfMData` and a list of `ImageDescriber` objects, and processes all views:
+
+```cpp
+aliceVision::featureEngine::FeatureExtractor extractor(sfmData);
+extractor.setOutputFolder("/path/to/features");
+extractor.addImageDescriber(siftDescriber);
+extractor.process(hardwareContext, image::EImageColorSpace::SRGB);
+```
+
+### Key features
+
+- Automatic dispatch between CPU and GPU describers
+- Optional image masking (mask folder, extension, inversion)
+- Range-based processing (for distributed computation)
+- Memory consumption estimation per view
+
+## FeatureExtractorViewJob
+
+The `FeatureExtractorViewJob` class represents the feature extraction work for a single view. It tracks which image describers run on the CPU versus the GPU and manages the output file paths:
+
+- `getFeaturesPath(imageDescriberType)` — path to the `.feat` file for a given describer type
+- `getDescriptorPath(imageDescriberType)` — path to the `.desc` file for a given describer type

src/aliceVision/fuseCut/README.md

@@ -0,0 +1,43 @@
+# fuseCut
+
+This module implements the volumetric reconstruction pipeline that converts multi-view depth maps into a 3D mesh using a graph-cut algorithm on a Delaunay tetrahedralization.
+
+## Overview
+
+The `fuseCut` module is responsible for the dense 3D reconstruction stage. It:
+
+1. Fuses depth maps from multiple cameras into a 3D point cloud
+2. Builds a Delaunay tetrahedralization of the point cloud
+3. Labels tetrahedra as "inside" or "outside" the surface using a min-cut / max-flow algorithm
+4. Extracts the mesh at the interface between inside and outside regions
+
+## Key Classes
+
+### Fuser
+
+The `Fuser` class filters and fuses depth maps across cameras:
+
+- `filterGroups()` / `filterGroupsRC()`: groups pixels across cameras to detect consistent depth estimates
+- `filterDepthMaps()` / `filterDepthMapsRC()`: removes depth map pixels that are not supported by enough cameras
+- `divideSpaceFromDepthMaps()` / `divideSpaceFromSfM()`: estimates the bounding box of the scene
+
+### Tetrahedralization
+
+The `Tetrahedralization` class builds a Delaunay tetrahedralization from the fused 3D points.
+
+### GraphFiller
+
+The `GraphFiller` class populates the graph with visibility-based weights used by the max-flow algorithm to determine the surface location.
+
+### Mesher
+
+The `Mesher` class extracts the final triangle mesh from the graph-cut result.
+
+### PointCloud
+
+The `PointCloud` class manages the 3D point cloud built from the fused depth maps, including point visibility information.
+
+## References
+
+- Labatut, P., Pons, J.-P., Keriven, R. *Efficient Multi-View Reconstruction of Large-Scale Scenes using Interest Points, Delaunay Triangulation and Graph Cuts.* ICCV 2007.
+- Jancosek, M., Pajdla, T. *Multi-View Reconstruction Preserving Weakly-Supported Surfaces.* CVPR 2011.

src/aliceVision/gpu/README.md

@@ -0,0 +1,40 @@
+# gpu
+
+This module provides utilities to query and check the availability of CUDA-capable GPU devices.
+
+## Overview
+
+The `gpu` module provides a small set of functions to detect GPU capabilities at runtime. It is used by other AliceVision modules to determine whether GPU-accelerated code paths are available.
+
+## API
+
+### `gpuSupportCUDA`
+
+```cpp
+bool gpuSupportCUDA(int minComputeCapabilityMajor,
+                    int minComputeCapabilityMinor,
+                    int minTotalDeviceMemory = 0);
+```
+
+Returns `true` if the system has at least one CUDA device meeting the specified minimum compute capability (major and minor version) and minimum total device memory (in MB).
+
+### `gpuInformationCUDA`
+
+```cpp
+std::string gpuInformationCUDA();
+```
+
+Returns a human-readable string describing all detected CUDA devices and their properties (compute capability, total memory, etc.).
+
+## Example
+
+```cpp
+#include <aliceVision/gpu/gpu.hpp>
+
+if (aliceVision::gpu::gpuSupportCUDA(3, 5, 2048))
+{
+    // GPU with compute capability >= 3.5 and >= 2 GB memory is available
+}
+
+std::cout << aliceVision::gpu::gpuInformationCUDA() << std::endl;
+```

src/aliceVision/graph/README.md

@@ -0,0 +1,36 @@
+# graph
+
+This module provides graph data structures and algorithms used throughout AliceVision, including indexed graphs, connected component analysis, and triplet enumeration.
+
+## Overview
+
+The `graph` module wraps the [Boost.Graph](https://www.boost.org/doc/libs/release/libs/graph/) library with AliceVision-specific types and adds higher-level algorithms commonly needed in Structure-from-Motion pipelines.
+
+## IndexedGraph
+
+The `IndexedGraph` class is a graph where nodes are identified by integer indices (`IndexT`). It supports directed and undirected edges.
+
+## Connected Components
+
+The `connectedComponent.hpp` header provides functions to compute and filter connected components of a graph:
+
+```cpp
+// Get all connected components of the graph
+std::set<std::set<IndexT>> components = aliceVision::graph::graphToConnectedComponents(graph);
+```
+
+## Triplets
+
+The `Triplet` struct and associated utilities enumerate all triplets (sets of three mutually connected nodes) in a graph. Triplets are used in Structure-from-Motion for rotation averaging and loop consistency checks:
+
+```cpp
+struct Triplet {
+    IndexT i, j, k;
+};
+std::vector<Triplet> triplets;
+aliceVision::graph::ListTriplets(graph, triplets);
+```
+
+## Graphviz Export
+
+The `indexedGraphGraphvizExport.hpp` header provides a function to export an `IndexedGraph` to the Graphviz DOT format for visualization.