Update doc building instructions

Author: paulinus

doc/source/annotation_tool.rst

@@ -49,9 +49,9 @@ Main toolbox
 ~~~~~~~~~~~~
 
 The main toolbox contains the list of existing control points as well as several controls.
-The basic controls are explained here. Scroll to :ref:`additional-controls` for information on the rest.
+The basic controls are explained here. Scroll to :ref:`advanced-features` for information on the rest.
 
-- The 'Load', 'Save' buttons save and load the ground control points into a ``ground_control_points.json`` file with :ref:`json-gcps`.
+- The 'Load', 'Save' buttons save and load the ground control points into a ``ground_control_points.json`` file (see the JSON file format section in the Ground Control Points documentation).
 - If there is a ``ground_control_points.json`` file in the dataset directory, it will be loaded upon launch.
 - Control points can be added or removed with the 'Add GCP' and 'Remove GCP' buttons. The active point can be selected from the dropdown.
 - By selecting a point in the list it becomes active and can be annotated on all images.
@@ -84,6 +84,7 @@ Assuming that you have a set of ground control points whose geodetic coordinates
    You can use ``data/berlin`` for this example.
 2. Generate a ``ground_control_points.json`` file with all your measured ground control points and place it in the root of the dataset
    See the example below. Note how the 'observations' is empty as we will generate those using the annotation tool.
+
 ::
 
     "points": [
@@ -93,6 +94,7 @@ Assuming that you have a set of ground control points whose geodetic coordinates
         "observations": []
       }
     ]
+
 3. Launch the annotation tool, note how the control points dropdown contains your ground control points.
 4. Scroll through all the images, annotating each GCP on all the locations where it is visible.
 5. Click on 'save' to overwrite the ``ground_control_points.json`` file with your annotations.
@@ -122,6 +124,8 @@ The 'Flex' and 'Full' buttons produce additional analysis results and
 are explained in :ref:`two-reconstruction-annotation`
 
 
+.. _advanced-features:
+
 Advanced features
 -----------------
 

doc/source/building.rst

@@ -6,18 +6,19 @@ Building
 
 Quick start
 -----------
+
 To build OpenSfM, follow these steps:
 
-1.  Download the OpenSfM code from Github
+1. Download the OpenSfM code from Github::
 
     git clone --recursive https://github.com/mapillary/OpenSfM
 
-2.  Install the dependencies (we recommend using conda)
+2. Install the dependencies (we recommend using conda)::
 
     conda env create --file conda.yml --yes
     conda activate opensfm
 
-3.  Build OpenSfM
+3. Build OpenSfM::
 
     pip install -e .
 
@@ -45,7 +46,7 @@ The way to install these dependencies depends on your system. We recommend using
 Installing dependencies using Conda (recommended)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Creating a conda environment will take care of installing all dependencies. Make sure you have conda or miniconda installed.  From the project root directory, run::
+Creating a conda environment will take care of installing all dependencies. Make sure you have conda or miniconda installed. From the project root directory, run::
 
     conda env create --file conda.yml --yes
 
@@ -58,19 +59,19 @@ and you are ready to build OpenSfM.
 (Anaconda dependencies installation has been tested under MacOS (Sequoia), Ubuntu 24.04 and Fedora 42.)
 
 Installing dependencies on Ubuntu
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you are not using conda, see this `Dockerfile.ubuntu24 <https://github.com/mapillary/OpenSfM/blob/main/Dockerfile.ubuntu24>`_ for the commands to install all dependencies on Ubuntu 24.04.
 
 
 Installing dependencies on MacOSX
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 While it is possible to install all dependencies using brew, we recommend using the conda instructions above instead.
 
 
 Installing dependencies on Windows
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Install git_.
 
@@ -101,23 +102,37 @@ Once the dependencies have been installed, you can build OpenSfM by running the
 
 This will first install python dependencies on your current python environment, and then build OpenSfM and install it in editable mode.
 
+
 Building Docker images
 ----------------------
 
-You can also use OpenSfM inside docker. We provide example Dockerfiles for Ubuntu 20.04 and 24.04.  Build it by running the following command from the main folder::
+You can also use OpenSfM inside docker. We provide example Dockerfiles for Ubuntu 20.04 and 24.04. Build it by running the following command from the main folder::
 
     docker build -t opensfm.ubuntu24 -f Dockerfile.ubuntu24 .
 
+
 Building the documentation
 --------------------------
-To build the documentation and browse it locally use::
 
-    pip install sphinx_rtd_theme
-    python setup.py build_doc
-    python -m http.server --directory build/doc/html/
+To build the documentation and browse it locally, first install Sphinx::
+
+    pip install -e .[docs]
+
+Then build the documentation using make::
+
+    cd doc
+    make html
+
+To browse the documentation locally::
+
+    make serve
 
 and browse `http://localhost:8000/ <http://localhost:8000/>`_
 
+To clean the build artifacts::
+
+    make clean
+
 
 .. _Github: https://github.com/mapillary/OpenSfM
 .. _release: https://github.com/mapillary/OpenSfM/releases

doc/source/conf.py

@@ -50,7 +50,7 @@
 
 # General information about the project.
 project = "OpenSfM"
-copyright = "2021, Mapillary"
+copyright = "2025, Mapillary"
 author = "Mapillary"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -67,7 +67,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/source/gcp.rst

@@ -12,8 +12,6 @@ In the bundle adjustment step, GCP observations are used as a constraint to refi
 
 GPSs can be specified in two file formats.  If existing, both are loaded.
 
-.. _json-gcps:
-
 JSON file format
 ~~~~~~~~~~~~~~~~
 GCPs can be specified by adding a text file named ``ground_control_points.json`` at the root folder of the dataset. The format of the file should be as follows::

doc/source/quality_report.rst

@@ -52,12 +52,12 @@ Reconstruction Details
 
 |rec|
 
- - Average reprojection error (normalized/pixels): normalized (by features uncertainty) average norm of reprojection errors and same, but pixel-wise,
- un-normalized, error. Errors bigger than 4 pixels are pruned out.
- - Average Track Length : average number of images in which a reconstructed points has been detected.
- - Average Track Length (> 2) : same as above but ignoring 2-images points.
+- Average reprojection error (normalized/pixels): normalized (by features uncertainty) average norm of reprojection errors and same, but pixel-wise,
+  un-normalized, error. Errors bigger than 4 pixels are pruned out.
+- Average Track Length : average number of images in which a reconstructed points has been detected.
+- Average Track Length (> 2) : same as above but ignoring 2-images points.
 
- |residual_histogram|
+|residual_histogram|
 
  The tables are the histogram of the certainty-normalized and un-normalized reprojection errors norm. Errors bigger than 4 pixels are pruned out.
 

doc/source/rig.rst

@@ -12,18 +12,19 @@ Coordinate Systems
 Rig are defined by a fixed assembly of cameras that are triggered at the same instant.
 The following terms define such assembly and capture in OpenSfM terminology :
 
- - A `RigCamera` is a camera of the rig assembly defined as a combination of an existing camera model (it refers only to its ID) and its pose wrt. the rig assembly coordinate frame. `RigCamera` are defined in the `rig_cameras.json` as the following::
+- A `RigCamera` is a camera of the rig assembly defined as a combination of an existing camera model (it refers only to its ID) and its pose wrt. the rig assembly coordinate frame. `RigCamera` are defined in the `rig_cameras.json` as the following::
 
- {
-    "RIG_CAMERA_ID":
     {
-        "translation": translation of the rig frame wrt. the RigCamera frame
-        "rotation": rotation bringing a point from rig frame to the RigCamera frame
-        "camera": camera model ID of this RigCamera
-    },
-    ...
+        "RIG_CAMERA_ID":
+        {
+            "translation": translation of the rig frame wrt. the RigCamera frame
+            "rotation": rotation bringing a point from rig frame to the RigCamera frame
+            "camera": camera model ID of this RigCamera
+        },
+        ...
+    }
 
- - A `RigInstance` is a list of `Shots`, each of which correspond to a `RigCamera` of the `RigModel` and the actual pose of the `RigModel` in the world : it's indeed an instantiation of the `RigModel` by combining `Shots`. These instances are defined in the `rig_assignments.json` file as follows::
+- A `RigInstance` is a list of `Shots`, each of which correspond to a `RigCamera` of the `RigModel` and the actual pose of the `RigModel` in the world : it's indeed an instantiation of the `RigModel` by combining `Shots`. These instances are defined in the `rig_assignments.json` file as follows::
 
     {
         "RIG_INSTANCE_ID1": {
@@ -57,8 +58,7 @@ The following terms define such assembly and capture in OpenSfM terminology :
             ]
         },
         ...
-
-
+    }
 
 A picture is often worth many words :
 |rig_frame|

doc/source/sensor_database.rst

@@ -9,7 +9,7 @@ Calibration Database
 Overview
 --------
 
-In order to produce accurate geometry, structure-from-motion (SfM) needs to have correct estimates of the imaging sensor geometry, such as : lens type (fisheye, perspective, spherical), focal, distorsion, principal point. Please refer to the `Geometric Models`_ section for a comprehensive list of camera internal parameters (calibration).
+In order to produce accurate geometry, structure-from-motion (SfM) needs to have correct estimates of the imaging sensor geometry, such as : lens type (fisheye, perspective, spherical), focal, distorsion, principal point. Please refer to the :doc:`geometry` section for a comprehensive list of camera internal parameters (calibration).
 
 While reconstructing the scene (using incremental SfM), OpenSfM will adjust for the camera calibration values that best explain the seen geometry. However, in order to get optimal and failsafe results, it is recommended to have a first good guess of the calibration values. By default, OpenSfM will try to get these values by reading the image EXIFs, where the focal length can be red, and is one of the most important of the calibration values. However, sometimes, EXIFs does not contain such value, or it is erroneous, and/or it is better to have other values than just the focal length.
 
@@ -21,18 +21,18 @@ Here comes sensors databases to the rescue. These are files stored under ``opens
 sensor_data_detailed.json
 -------------------------
 
-This file contains physical sensor's width and height, in millimeters, for a given ``model make`` sensor (see `extract_metadata`_). It means that if only the focal length is available in the EXIFs, since we also have the sensor physical size, we know the full sensor geometry.
+This file contains physical sensor's width and height, in millimeters, for a given ``model make`` sensor (see ``extract_metadata`` command). It means that if only the focal length is available in the EXIFs, since we also have the sensor physical size, we know the full sensor geometry.
 
 
 sensor_data.json
 ----------------
 
-This file contains a multiplicative factor for a given ``model make`` sensor (see `extract_metadata`_). When applied to the EXIFs focal length, this factor gives the focal 35mm equivalent. Since we know the dimensions of 35mm equivalent (24x32 mm), we again know the full sensor geometry.
+This file contains a multiplicative factor for a given ``model make`` sensor (see ``extract_metadata`` command). When applied to the EXIFs focal length, this factor gives the focal 35mm equivalent. Since we know the dimensions of 35mm equivalent (24x32 mm), we again know the full sensor geometry.
 
 camera_calibration.json
 ------------------------
 
-This file contains the full definition (in OpenSfM format) of camera calibrations. Calibration are for a given ``make`` (see `extract_metadata`_), and then, they're further refined :
+This file contains the full definition (in OpenSfM format) of camera calibrations. Calibration are for a given ``make`` (see ``extract_metadata`` command), and then, they're further refined :
  - If ``ALL`` is specified, then the calibration is valid for all ``make model`` camera independant of their ``model`` value
  - If ``MODEL`` is specified, then calibrations are per actual ``model``
  - If ``FOCAL`` is specified, then calibrations are per focal length red from the EXIFs

doc/source/using.rst

@@ -22,7 +22,7 @@ First, build the OpenSfM Docker image, as described under "building".
 
 Then, start a Docker container. The following command mounts the `data/` folder to `/data/` inside the Docker container::
 
-    docker run -it -p 8080:8080 -v ${PWD}/data/:/data/ opensfm:ceres2
+    docker run -it -p 8080:8080 -v ${PWD}/data/:/data/ opensfm.ubuntu24 /bin/bash
 
 Once inside the running Docker container, start the reconstruction process with the usual command::
 
@@ -316,4 +316,4 @@ Checkout `the default configuration <_modules/opensfm/config.html>`_ to see the
 
 
 .. include:: gcp.rst
-.. _fisheye https://docs.opencv.org/master/db/d58/group__calib3d__fisheye.html
+.. _fisheye: https://docs.opencv.org/master/db/d58/group__calib3d__fisheye.html