Add documentations (#38)

* intiail sphinx setup * docs structure setup * installation docs * quickstart docs * fix highlights * Localization and autodocs * minor * fix a cross-ref link in docstring * update setup. * now it works!!! as far as I know * minor update. * Support google style docstring * docs for Line2d and Line3d * A helper script to help build the doc of C++ part * Change to google style docstrings * refactor localization tutorial * minor * Finish documenting lines, and some formatting * reformat types * Fix property stack on same line * Documenting estimators, rename ExtendedHybridLORansacOptions -> HybridLORansacOptions (python only) * Finish doc for limap.base * Minor fix for the merge * update torch version. * minor. * update. * add docs for evaluation package. remove line2d + point2d from the docs. * fix. * Minor fix to solve sphinx warnings * update. change undistortion interface. add docs for visualization and undistortion. * minor. * minor. * To make sphinx and Shaohui happy * docs for line2d, vp, triangulation and undistortion. * restructure tests folder * adapt to new hloc convention. support features other than superpoint. * docs for limap/runners/functions * docs for main runners. * minor. * update. * update tutorials. * update readme. * update. * update teaser and main descriptions in docs. * remove indexes. * minor update. * minor fix. * Create .readthedocs.yaml * minor fix. * fix the last commit. --------- Co-authored-by: Yifan Yu <[email protected]>
cvg · Jul 26, 2023 · 6ea1aae · 6ea1aae
1 parent e6bd1ce
commit 6ea1aae
Show file tree

Hide file tree

Showing 82 changed files with 2,552 additions and 339 deletions.
diff --git a/.gitignore b/.gitignore
@@ -24,3 +24,4 @@ results
 outputs
 tmp
 
+docs/_build
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
@@ -1,12 +1,11 @@
 # LIMAP 
+
+**The documentations on brief tutorials and APIs are available [here](http://b1ueber2y.me/projects/LIMAP/docs/)**.
+
 <p align="center">
 <img src="./misc/media/supp_qualitative_5x3.png">
 </p>
 
-----------------------------------------------------------------
-**Note**: More README and docs will be available soon.
-----------------------------------------------------------------
-
 LIMAP is a toolbox for mapping and localization with line features. The system was initially described in the highlight paper [3D Line Mapping Revisited](https://arxiv.org/abs/2303.17504) at CVPR 2023 in Vancouver, Canada. Contributors to this project are from the [Computer Vision and Geometry Group](https://cvg.ethz.ch/) at [ETH Zurich](https://ethz.ch/en.html).
 
 In this project, we provide interfaces for various geometric operations on 2D/3D lines. We support off-the-shelf SfM software including [VisualSfM](http://ccwu.me/vsfm/index.html), [Bundler](https://bundler.io/), and [COLMAP](https://colmap.github.io/) to initialize the camera poses to build 3D line maps on the database. The line detectors, matchers, and vanishing point estimators are abstracted to ensure flexibility to support recent advances and future development. 

diff --git a/cfgs/examples/fitting_3Dline.yaml b/cfgs/examples/fitting_3Dline.yaml
@@ -0,0 +1,8 @@
+
+# fitting config
+fitting:
+    var2d: 4.0 # This is for DeepLSD. This hyperparameter should depend on the detector
+    ransac_th: 0.75
+    min_percentage_inliers: 0.9
+    n_jobs: 4
+
diff --git a/cfgs/examples/line2d_detect.yaml b/cfgs/examples/line2d_detect.yaml
@@ -0,0 +1,22 @@
+# global config
+dir_save: "tmp" 
+
+# loading config 
+load_det: False
+dir_load: null
+skip_exists: False
+
+# line detection and description config
+line2d:
+    max_num_2d_segs: 3000
+    do_merge_lines: False 
+    visualize: False
+    save_l3dpp: False
+    compute_descinfo: False
+    detector: 
+        method: "deeplsd" # ["lsd", "sold2", "hawpv3", "tp_lsd", "deeplsd"]
+        skip_exists: False
+    extractor: 
+        method: "wireframe" # ["sold2", "lbd", "l2d2", "linetr", "superpoint_endpoints", "wireframe"]
+        skip_exists: False
+
diff --git a/cfgs/examples/line2d_match.yaml b/cfgs/examples/line2d_match.yaml
@@ -0,0 +1,22 @@
+# global config
+dir_save: "tmp" 
+
+# loading config 
+load_match: False
+dir_load: null
+skip_exists: False
+
+# line matching config
+line2d:
+    detector: 
+        method: "deeplsd" # ["lsd", "sold2", "hawpv3", "tp_lsd", "deeplsd"]
+    extractor: 
+        method: "wireframe" # ["sold2", "lbd", "l2d2", "linetr", "superpoint_endpoints", "wireframe"]
+    matcher:
+        method: "gluestick" # ["sold2", "lbd", "l2d2", "linetr", "nn_endpoints", "superglue_endpoints", "gluestick"]
+        n_jobs: 1
+        topk: 10
+        skip_exists: False
+        superglue:
+            weights: "outdoor" # ["indoor", "outdoor"] for selecting superglue models
+
diff --git a/cfgs/examples/pointsfm.yaml b/cfgs/examples/pointsfm.yaml
@@ -0,0 +1,22 @@
+# global config
+dir_save: "tmp" 
+n_neighbors: 20
+
+# loading config 
+load_meta: False
+dir_load: null
+skip_exists: False
+
+# sfm config
+sfm: 
+    colmap_output_path: "colmap_outputs"
+    reuse: False
+    min_triangulation_angle: 1.0
+    neighbor_type: "dice" # ["overlap", "iou", "dice"]
+    ranges:
+        range_robust: [0.05, 0.95]
+        k_stretch: 1.25
+    hloc:
+        descriptor: "superpoint_aachen"
+        matcher: "NN-superpoint"
+
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/css/fix-rtd-property.css b/docs/_static/css/fix-rtd-property.css
@@ -0,0 +1,3 @@
+dl.py.property {
+    display: block !important;
+}
diff --git a/docs/api/limap.base.camera.rst b/docs/api/limap.base.camera.rst
@@ -0,0 +1,28 @@
+Cameras, poses, and images
+==============================
+
+.. autoclass:: limap.base.Camera
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+.. autoclass:: limap.base.CameraImage
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+.. autoclass:: limap.base.CameraPose
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+.. autoclass:: limap.base.CameraView
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+.. autoclass:: limap.base.ImageCollection
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
diff --git a/docs/api/limap.base.line_dists.rst b/docs/api/limap.base.line_dists.rst
@@ -0,0 +1,8 @@
+Line distance
+================
+
+.. autoclass:: limap.base.LineDistType
+.. autofunction:: limap.base.compute_distance_2d
+.. autofunction:: limap.base.compute_distance_3d
+.. autofunction:: limap.base.compute_pairwise_distance_2d
+.. autofunction:: limap.base.compute_pairwise_distance_3d
diff --git a/docs/api/limap.base.lines.rst b/docs/api/limap.base.lines.rst
@@ -0,0 +1,26 @@
+Lines
+===========
+
+.. autoclass:: limap.base.Line2d
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+
+.. autoclass:: limap.base.Line3d
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+
+.. autoclass:: limap.base.InfiniteLine2d
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+
+.. autoclass:: limap.base.InfiniteLine3d
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
diff --git a/docs/api/limap.base.linetrack.rst b/docs/api/limap.base.linetrack.rst
@@ -0,0 +1,8 @@
+Line track
+================
+
+.. autoclass:: limap.base.LineTrack
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
diff --git a/docs/api/limap.base.reader.rst b/docs/api/limap.base.reader.rst
@@ -0,0 +1,19 @@
+Readers for depths and point clouds
+===============================================
+
+limap.base.depth\_reader\_base module
+-------------------------------------
+
+.. automodule:: limap.base.depth_reader_base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+limap.base.p3d\_reader\_base module
+-----------------------------------
+
+.. automodule:: limap.base.p3d_reader_base
+   :members:
+   :undoc-members:
+
+
diff --git a/docs/api/limap.base.rst b/docs/api/limap.base.rst
@@ -0,0 +1,17 @@
+limap.base package
+==================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Module Contents: 
+
+   limap.base.camera
+   limap.base.lines
+   limap.base.line_dists
+   limap.base.linetrack
+   limap.base.reader
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Submodules: 
+
diff --git a/docs/api/limap.estimators.absolute_pose.rst b/docs/api/limap.estimators.absolute_pose.rst
@@ -0,0 +1,6 @@
+Estimate absolute pose
+=======================================
+
+.. automodule:: limap.estimators.absolute_pose
+   :members:
+   :show-inheritance:
diff --git a/docs/api/limap.estimators.ransac.rst b/docs/api/limap.estimators.ransac.rst
@@ -0,0 +1,18 @@
+RANSAC options and statistics
+==============================
+
+.. autoclass:: limap.estimators.RansacStatistics
+   :members:
+   :undoc-members:
+.. autoclass:: limap.estimators.RansacOptions
+   :members:
+   :undoc-members:
+.. autoclass:: limap.estimators.LORansacOptions
+   :members:
+   :undoc-members:
+.. autoclass:: limap.estimators.HybridRansacStatistics
+   :members:
+   :undoc-members:
+.. autoclass:: limap.estimators.HybridLORansacOptions
+   :members:
+   :undoc-members:
diff --git a/docs/api/limap.estimators.rst b/docs/api/limap.estimators.rst
@@ -0,0 +1,20 @@
+limap.estimators package
+========================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Subpackages:
+
+   limap.estimators.absolute_pose
+
+.. .. automodule:: limap.estimators
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Module Contents:
+
+   limap.estimators.ransac
+
diff --git a/docs/api/limap.evaluation.mesh_evaluator.rst b/docs/api/limap.evaluation.mesh_evaluator.rst
@@ -0,0 +1,9 @@
+Evaluate w.r.t. a Mesh 
+==============================
+
+.. autoclass:: limap.evaluation.MeshEvaluator
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+
diff --git a/docs/api/limap.evaluation.point_cloud_evaluator.rst b/docs/api/limap.evaluation.point_cloud_evaluator.rst
@@ -0,0 +1,9 @@
+Evaluate w.r.t. a Point Cloud 
+==============================
+
+.. autoclass:: limap.evaluation.PointCloudEvaluator
+   :members:
+   :undoc-members: 
+   :special-members: __init__
+   :member-order: groupwise
+
diff --git a/docs/api/limap.evaluation.rst b/docs/api/limap.evaluation.rst
@@ -0,0 +1,10 @@
+limap.evaluation package
+========================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Module Contents: 
+
+   limap.evaluation.mesh_evaluator
+   limap.evaluation.point_cloud_evaluator
+
diff --git a/docs/api/limap.line2d.base_detector.rst b/docs/api/limap.line2d.base_detector.rst
@@ -0,0 +1,9 @@
+Base line detector/descriptor
+----------------------------------
+
+.. automodule:: limap.line2d.base_detector
+   :members:
+   :show-inheritance:
+   :member-order: groupwise
+
+
diff --git a/docs/api/limap.line2d.base_matcher.rst b/docs/api/limap.line2d.base_matcher.rst
@@ -0,0 +1,8 @@
+Base line matcher
+---------------------------------
+
+.. automodule:: limap.line2d.base_matcher
+   :members:
+   :show-inheritance:
+
+
diff --git a/docs/api/limap.line2d.register_detector.rst b/docs/api/limap.line2d.register_detector.rst
@@ -0,0 +1,8 @@
+Instantiate a line detector/descriptor
+-------------------------------------------------------------
+
+.. automodule:: limap.line2d.register_detector
+   :members:
+   :show-inheritance:
+
+
diff --git a/docs/api/limap.line2d.register_matcher.rst b/docs/api/limap.line2d.register_matcher.rst
@@ -0,0 +1,7 @@
+Instantiate a line matcher
+-------------------------------------
+
+.. automodule:: limap.line2d.register_matcher
+   :members:
+   :show-inheritance:
+
diff --git a/docs/api/limap.line2d.rst b/docs/api/limap.line2d.rst
@@ -0,0 +1,12 @@
+limap.line2d package
+====================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Module Contents: 
+
+   limap.line2d.base_detector
+   limap.line2d.register_detector
+   limap.line2d.base_matcher
+   limap.line2d.register_matcher
+