Installation Guide

This document describes PoSDK installation requirements and procedures.

System Requirements

  • Operating System:

    • Primary Support: macOS | Ubuntu 24.04 LTS (Recommended)

    • Secondary Support: Other Linux distributions (Ubuntu 20.04+/CentOS 7)

    • Planned Support: Windows (future versions)

  • Compiler: C++17 compatible compiler

    • GCC 11+ (Recommended for Linux)

    • Clang 13+ (Recommended for macOS)

  • Build Tools: CMake 3.28+ (3.28+ required for some dependency libraries)

One-Click Installation

PoSDK provides an automated installation script that can install all required system dependencies and plugin dependencies with one command. See Quick Start for detailed installation steps.

The installation script automatically completes the following steps:

  1. Update system package list

  2. Install PoSDK framework development dependencies

  3. Install dependencies required by current plugins

PoSDK Framework Development Dependencies

The following are system dependency libraries required for normal operation of the PoSDK framework:

Dependency Library

Minimum Version

Purpose

Installation Command

build-essential

-

C++ compiler and build tools

sudo apt install -y build-essential

CMake

3.28+

Build system generator (3.28+ required for some libraries)

Built from source (see install_cmake.sh) or sudo apt install -y cmake

Eigen3

3.3+

Linear algebra library for matrix and vector ops

sudo apt install -y libeigen3-dev

SuiteSparse

7.0+

Sparse matrix computation library (includes CHOLMOD)

sudo apt install -y libsuitesparse-dev

OpenBLAS

0.3.20+

Optimized BLAS library for high-performance linear algebra

sudo apt install -y libopenblas-dev

Boost

1.85.0

C++ extension library (mainly filesystem and system)

Built from source (see install_boost.sh)

Protobuf

4.33.0

Data serialization library

Built from source (see install_protobuf.sh)

nlohmann_json

3.11.2

C++ JSON parsing library

Built from source (see install_nlohmann.sh)

gflags

2.2+

Command-line argument parsing library

sudo apt install -y libgflags-dev

GTest

1.10+

Unit testing framework

sudo apt install -y libgtest-dev

OpenCV

4.x

Computer vision library

Built from source (see install_opencv.sh)

glog

-

Google logging library

sudo apt install -y libgoogle-glog-dev

Abseil

-

Google base library

Built from source (see install_absl.sh)

Ceres Solver

2.2.0

Nonlinear optimization library

Built from source (see install_ceres.sh)

CURL

-

HTTP/HTTPS request library

sudo apt install -y libcurl4-openssl-dev

OpenGL

-

3D graphics rendering library

sudo apt install -y libgl1-mesa-dev mesa-common-dev libglu1-mesa-dev freeglut3-dev

GLFW3

-

Window and input management library

sudo apt install -y libglfw3-dev

Qt6

-

GUI development framework (optional)

sudo apt install qt6-base-dev qt6-declarative-dev

Detailed Installation Process

This section details PoSDK’s multi-stage installation process, helping you understand the purpose of each installation step and when to skip redundant installations.

Installation Process Overview

PoSDK installation is divided into three main stages:

┌─────────────────────────────────────────────────────────────┐
│  Stage 1: System Dependency Installation (install.sh)        │
│  ├─ System packages (apt/brew)                              │
│  ├─ Build tools (cmake, make, gcc/clang)                   │
│  └─ System libraries (Eigen, Boost, OpenCV, etc.)          │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 2: Dependency Download and Source Installation        │
│        (install_dependencies.sh)                            │
│  ├─ download_dependencies.sh → Download dependencies package│
│  ├─ download_po_core.sh → Download po_core binaries        │
│  └─ Individual library installations (see below)            │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Stage 3: PoSDK Main Project Build (cmake + make)            │
│  ├─ Configure with CMake                                    │
│  ├─ Build PoSDK core and plugins                           │
│  └─ Deploy output/ directory                               │
└─────────────────────────────────────────────────────────────┘

Dependency Installation Order and Skip Strategy

install_dependencies.sh installs 13 dependency libraries in the following order, with each library checking for existing installations:

Step

Dependency Library

Purpose

Installation Script

Skip Detection

When to Skip

0

CMake

Build system (optional if version meets requirements)

install_cmake.sh

CMake version check (requires 3.28+ for some libraries)

Version meets requirements (3.28+)

1

Boost

C++ library (requires 1.85.0)

install_boost.sh

Installation directory exists with headers and libs

Installed with correct version (1.85.0)

2

Abseil

Google base library (C++ stdlib extension)

install_absl.sh

CMake config file (abslConfig.cmake)

After first installation, unless version update needed

3

nlohmann/json

JSON parsing library (header-only)

install_nlohmann.sh

CMake config file (nlohmann_jsonConfig.cmake)

Installed and functioning properly

4

Protocol Buffers

Data serialization library

install_protobuf.sh

CMake config file (protobuf-config.cmake)

Installed and compatible with Abseil version

5

OpenCV

Computer vision library

install_opencv.sh

CMake config file (OpenCVConfig.cmake) + version info

Installed with version meeting requirements

6

Ceres Solver

Nonlinear optimization library

install_ceres.sh

CMake config file (CeresConfig.cmake) + library files

Installed with correct version (2.2.0)

7

MAGSAC

Robust estimation algorithm library

install_magsac.sh

Library files (.so/.dylib/.a)

Installed and functioning properly

8

OpenGV

Geometric vision library

install_opengv.sh

Library files (.so/.dylib/.a)

Installed and functioning properly

9

PoseLib

Pose estimation library

install_poselib.sh

Library files (.so/.dylib/.a)

Installed and functioning properly

10

OpenMVG

Multi-view geometry library

install_openmvg.sh

Executable files (openMVG_main_*)

Installed and functioning properly

11

COLMAP

SfM library

install_colmap.sh

Executable file (bin/COLMAP) + version info

Installed and functioning properly

12

GraphOptim

Graph optimization library (depends on COLMAP)

install_graphoptim.sh

Executable or library files (rotation_estimator)

Installed and COLMAP not updated

13

GLOMAP

Global SfM library

install_glomap.sh

Executable file (GLOMAP command)

Installed and functioning properly

Note:

  • These dependency libraries are automatically compiled and installed from source code in the dependencies/ directory

  • Installation scripts install in the order above to ensure correct dependency relationships

  • All dependency source code should be pre-placed in corresponding subdirectories under dependencies/

Detailed Installation Prompt Explanations

During installation, you will encounter the following prompt points. The meaning and recommendations for each are as follows:

Stage

Script File

Prompt Message

Default

Meaning

Recommended Action

System Deps

install.sh

Would you like to upgrade Qt now?

[Y/n]

Asks if upgrade Qt when version is too old

Press Enter (upgrade Qt to avoid conflicts)

System Deps

install.sh

Would you like to fix this automatically?

[y/N]

Asks if auto-fix when Qt version conflict detected

Press Enter (don’t auto-fix, manual handling safer)

System Deps

install.sh

Continue with Qt6 installation?

[y/N]

Asks if continue installing Qt6 when Qt5 detected

Press Enter (skip Qt6 installation to avoid conflicts)

Download

download_dependencies.sh

Skip download and use local package?

[Y/n]

Asks if skip download and use local package

Press Enter (use local package, extract all and overwrite existing)

Download

download_po_core.sh

Skip reinstall and use existing po_core installation?

[Y/n]

Asks if skip reinstall when po_core detected

Press Enter (skip installation to save time)

Download

download_po_core.sh

Skip download and use local package?

[Y/n]

Asks if skip download when local po_core package detected

Press Enter (use local package to save bandwidth)

Test Data

download_Strecha.sh

Do you want to re-download test data?

[y/N]

Asks if re-download when test data exists

Press Enter (skip re-download)

Test Data

download_Strecha.sh

Skip download and use existing local package?

[Y/n]

Asks if skip download when local test data package detected

Press Enter (use local package)

Build Deps

install_cmake.sh

Version sufficient, skip installation?

[Y/n]

Asks if skip installation when CMake version sufficient

Press Enter (skip installation to save time)

Build Deps

install_boost.sh

Skip rebuild and use existing Boost installation?

[Y/n]

Asks if skip rebuild when Boost detected

Press Enter (skip rebuild)

Build Deps

install_absl.sh

Do you want to skip this installation and use the existing build?

[Y/n]

Asks if skip installation when Abseil detected

Press Enter (skip installation)

Build Deps

install_nlohmann.sh

Do you want to skip this installation and use the existing build?

[Y/n]

Asks if skip installation when nlohmann/json detected

Press Enter (skip installation)

Build Deps

install_protobuf.sh

Do you want to skip this installation and use the existing build?

[Y/n]

Asks if skip installation when Protocol Buffers detected

Press Enter (skip installation)

Build Deps

install_opencv.sh

(No skip prompt, automatically detects and uses existing installation)

-

OpenCV installation script auto-detects and uses existing installation

No action needed (auto-handled)

Build Deps

install_ceres.sh

Skip rebuild and use existing Ceres Solver installation?

[Y/n]

Asks if skip rebuild when Ceres detected

Press Enter (skip rebuild to save time)

Build Deps

install_magsac.sh

Skip rebuild and use existing MAGSAC installation?

[Y/n]

Asks if skip rebuild when MAGSAC detected

Press Enter (skip rebuild)

Build Deps

install_opengv.sh

Skip rebuild and use existing OpenGV installation?

[Y/n]

Asks if skip rebuild when OpenGV detected

Press Enter (skip rebuild)

Build Deps

install_poselib.sh

Skip rebuild and use existing PoseLib installation?

[Y/n]

Asks if skip rebuild when PoseLib detected

Press Enter (skip rebuild)

Build Deps

install_openmvg.sh

Skip rebuild and use existing OpenMVG installation?

[Y/n]

Asks if skip rebuild when OpenMVG detected

Press Enter (skip rebuild)

Build Deps

install_colmap.sh

Skip rebuild and use existing COLMAP installation?

[Y/n]

Asks if skip rebuild when COLMAP detected

Press Enter (skip rebuild)

Build Deps

install_graphoptim.sh

Skip rebuild and use existing GraphOptim build?

[Y/n]

Asks if skip rebuild when GraphOptim detected

Press Enter (skip rebuild)

Build Deps

install_graphoptim.sh

Skip building internal COLMAP support (build core only)?

[Y/n]

Asks if skip building internal COLMAP support

Press Enter (skip COLMAP support, build core only)

Build Deps

install_glomap.sh

Skip this installation and use existing build? [Y/n]

[Y/n]

Asks if skip installation when GLOMAP detected

Press Enter (skip installation)

Build Deps

install_glomap.sh

Use local dependencies for build?

[Y/n]

Asks if use local dependencies to build GLOMAP

Press Enter (use local dependencies)

Error Handling

install_dependencies.sh

Continue with remaining installations?

[Y/n]

Asks if continue with remaining when a dependency fails

Press Enter (continue installing other dependencies)

Important

Default Values Usage:

For first-time installation and normal use cases, press Enter to use default values for all prompts.

Default value design principles:

  • [Y/n] Default skip redundant operations to save time and resources

  • [y/N] Default conservative actions to avoid accidental overwrites or conflicts

Manual selection needed in the following cases:

  • Force Rebuild: Suspect a dependency installation issue, enter n to force reinstall

  • Version Update: Need to update to latest version, enter n to redownload and rebuild

  • Troubleshooting: Errors during installation, need to reinstall specific components

Tip

Skip Detection Notes:

  • CMake Config Files: Check if standard CMake config files exist (e.g., OpenCVConfig.cmake) to ensure libraries can be found by CMake

  • Library Files: Check if build artifacts (.so, .dylib, .a) exist in installation directory

  • Executable Files: Check if program binary files exist and are executable

  • Version Information: Some libraries (OpenCV, COLMAP) additionally display installed version numbers

Quick Start

You can quickly launch the PoSDK Global SfM pipeline by following these steps:

Prerequisites

See System Requirements for detailed requirements. Minimum requirements:

  • CMake 3.28+ (required for some dependency libraries)

  • C++17 compatible compiler

  • Git

Step 1: Clone Repository and Install

# 1. Clone repository
git clone https://github.com/pose-only-vision/PoSDK.git
cd PoSDK

# 2. One-click installation (supports resume on timeout)
./install.sh

Features:

  • Resume Installation - Re-run ./install.sh if network timeouts occur

  • Automated Setup - Downloads dependencies, builds PoSDK, and prepares test data

  • Skip Detection - Automatically detects existing installations and prompts to skip (default: Y)

Tip

Default Values:

For normal installation: Press Enter (default values) to complete the installation, no additional selection needed.

For detailed explanation of each installation step and prompt, see Detailed Installation Process.

Note

For Poor Network Conditions: If automatic download fails, manually download from GitHub Releases and copy files directly (no extraction needed):

  • po_core + PoSDK dependencies → ./dependencies/

  • PoSDK_test_data → ./tests/

Then run ./install.sh to complete setup.

Step 2: Build PoSDK (if not done during installation)

mkdir build && cd build
cmake ..
make -j$(nproc)

Build Output Directory Structure

After successful build, PoSDK generates an output directory in the build folder with the following structure:

output/
├── bin/                          # Executable files directory
│   ├── PoSDK                    # PoSDK main program
│   └── globalsfm_pipeline_work/ # Working directory (generated at runtime)
├── lib/                          # Library files directory
│   ├── libposdk_agg.dylib/.so   # PoSDK aggregate library
│   └── cmake/                   # CMake configuration files
├── include/                      # Header files directory
│   ├── po_core/                 # po_core core headers
│   ├── pomvg/                   # PoSDK version info headers
│   ├── common/                  # PoSDK common headers
│   ├── plugins/                 # Plugin interface headers
│   ├── cereal/                  # Serialization library headers
│   └── lemon/                   # Graph optimization library headers
├── configs/                      # Configuration files directory
│   ├── methods/                 # Method plugin configurations
│   │   ├── globalsfm_pipeline.ini      # Global SfM pipeline config
│   │   ├── method_img2features.ini     # Feature extraction config
│   │   ├── method_img2matches.ini      # Feature matching config
│   │   ├── method_rotation_averaging.ini # Rotation averaging config
│   │   ├── TwoViewEstimator.ini        # Two-view estimator config
│   │   └── ...                         # Other method configs
│   └── data/                    # Data plugin configurations (optional)
├── plugins/                      # Plugin libraries directory
│   ├── methods/                 # Method plugins
│   │   ├── libglobalsfm_pipeline.dylib/.so       # Global SfM pipeline plugin
│   │   ├── libimg2features_pipeline.dylib/.so    # Feature extraction plugin
│   │   ├── libimg2matches_pipeline.dylib/.so     # Feature matching plugin
│   │   ├── libmethod_rotation_averaging.dylib/.so # Rotation averaging plugin
│   │   ├── libTwoViewEstimator.dylib/.so         # Two-view estimator plugin
│   │   └── ...                                   # Other method plugins
│   └── data/                    # Data plugins (optional)
├── python/                       # Python tools directory
│   ├── conda_env/               # Conda environment configuration
│   ├── colmap_pipeline/       # COLMAP preprocessing tools
│   ├── glomap_pipeline/       # GLOMAP preprocessing tools
│   ├── img2features_pipeline/   # Feature extraction pipeline tools
│   └── img2matches_pipeline/    # Feature matching pipeline tools
├── tests/                        # Test data directory (CMake auto-copied)
│   └── Strecha/                 # Strecha dataset
│       ├── castle-P19/          # Castle dataset (19 images)
│       ├── castle-P30/         # Castle dataset (30 images)
│       ├── entry-P10/          # Entry dataset (10 images)
│       ├── fountain-P11/        # Fountain dataset (11 images)
│       ├── Herz-Jesus-P8/      # Church dataset (8 images)
│       └── Herz-Jesus-P25/     # Church dataset (25 images)
└── common/                       # Common resources directory
    └── converter/               # Data converters

Note

Directory Descriptions:

  • bin/: Contains all executable files and runtime-generated data directories

  • lib/: Contains PoSDK aggregate library and CMake configurations

  • include/: Contains all header files needed for development (public interfaces)

  • configs/: Contains all plugin configuration files (read at runtime)

  • plugins/: Contains all dynamically loaded plugin libraries

  • python/: Contains Python auxiliary tools and scripts

  • tests/: Contains test datasets (automatically copied from source directory)

  • common/: Contains common resources and data definitions

Tip

Development Tips:

  1. Modify configuration files directly in output/configs/methods/ without rebuilding

  2. Test data default path is {exe_dir}/../tests/Strecha, use relative paths in config files

Step 3: Run PoSDK

# Run PoSDK from build directory
./output/bin/PoSDK

Step 4: View Results

PoSDK generates results in the working directory:

Directory Structure

  • globalsfm_pipeline_work/ - Main working directory (configured in globalsfm_pipeline.ini)

  • [dataset_name]/ - Individual dataset results with 3D reconstruction and MeshLab outputs

  • summary/ - Performance analysis and evaluation reports

Summary Reports

Report File

Description

profiler_performance_summary.csv

Performance Metrics - CPU, memory usage, and execution timing

summary_GlobalPoses_rotation_error_deg_ALL_STATS.csv

Global Rotation Accuracy - Statistical analysis of rotation estimation errors

summary_GlobalPoses_translation_error_ALL_STATS.csv

Global Translation Accuracy - Statistical analysis of translation estimation errors

summary_RelativePoses_rotation_error_deg_ALL_STATS.csv

Relative Rotation Accuracy - Pairwise rotation error statistics

summary_RelativePoses_translation_error_deg_ALL_STATS.csv

Relative Translation Accuracy - Pairwise translation error statistics

Verification

After successful installation and run, you should see:

  • Console Output: Step-by-step progress and performance statistics

  • Working Directory: globalsfm_pipeline_work/ containing:

    • storage/features/ - Feature extraction results

    • storage/matches/ - Feature matching results

    • storage/poses/ - Pose estimation results

  • Evaluation Reports: Accuracy evaluation and comparative analysis results

Troubleshooting

If encountering runtime issues:

  1. Check Dependency Paths:

    ldd output/bin/PoSDK  # Linux: check dynamic library dependencies
otool -L output/bin/PoSDK  # macOS: check dynamic library dependencies

  2. Check Configuration Files: Ensure output/configs/methods/globalsfm_pipeline.ini exists and path configuration is correct

  3. Common Issues:

    • OpenGV not found: Run cd src/dependencies && ./install_opengv.sh

    • Configuration file not found: Ensure complete cmake build process was run

FAQ and Troubleshooting

Common Installation Issues

1. Qt Version Conflicts on macOS

Symptoms:

Error: The `brew link` step did not complete successfully
Could not symlink share/qt/metatypes/qt6bluetooth_release_metatypes.json
Target /opt/homebrew/share/qt/metatypes/qt6bluetooth_release_metatypes.json
is a symlink belonging to qt. You can unlink it:
  brew unlink qt

Cause:

  • Qt module version (e.g., 6.9.3) required by OpenCV conflicts with system-installed Qt version (e.g., 6.8.2)

  • Simultaneous installation of qt@5 and qt causes symlink conflicts

Solutions:

Solution 1: Upgrade Qt to latest version

brew upgrade qt

This automatically upgrades qt and related dependencies (opencv, pyqt, vtk, etc.)

Solution 2: Manually resolve link conflicts

# If both qt@5 and qt exist
brew unlink qt@5           # Unlink qt@5
brew unlink qt             # Temporarily unlink qt
brew link --overwrite qt   # Re-link qt (overwrite conflicts)

Solution 3: Uninstall qt@5 (if not needed)

# Check which packages depend on qt@5
brew uses --installed qt@5
# If only pyqt@5 depends and not needed
brew uninstall pyqt@5 qt@5

Verify Qt Version:

brew list --versions qt    # View installed qt versions
brew info qt               # View latest stable qt version

2. Dependency Library Installation Failures

Issue: A dependency library compilation/installation failed

Solution:

  • Check error logs to identify specific failure cause

  • Ensure prerequisites for that dependency library are met

  • Can reinstall the dependency individually:

    cd dependencies
./install_<dependency_name>.sh

3. CMake Version Too Low

Issue: CMake version is below 3.28

Solution:

Ubuntu:

# Solution 1: Install latest using snap
sudo snap install cmake --classic

# Solution 2: Download from official website
wget https://github.com/Kitware/CMake/releases/download/v3.27.0/cmake-3.27.0-linux-x86_64.sh
sudo bash cmake-3.27.0-linux-x86_64.sh --prefix=/usr/local --skip-license

macOS:

brew upgrade cmake

4. Network Issues Causing Dependency Download Failures

Solution:

  • Manually download dependency packages from GitHub Releases: PoSDK Releases

  • Place downloaded files in corresponding directories:

    • po_core + dependency packages → ./dependencies/

    • Test data → ./tests/

  • Re-run ./install.sh (script will skip already downloaded content)

System Requirements Check

If encountering installation issues, first verify the System Requirements are met:

  • CMake Version: Ensure CMake version is 3.28 or higher

    cmake --version

  • Dependency Library Paths: Check if all source directories exist under dependencies/ directory

    ls dependencies/

  • Build Tools: Ensure gcc/g++ and make are correctly installed

    gcc --version    # Linux
clang --version  # macOS
make --version

  • Log Output: Check installation script output logs to understand specific failure steps

Getting Help

If the issue remains unresolved:

  1. Check this FAQ for related issues

  2. Refer to official documentation for each dependency library

  3. Submit an issue at PoSDK GitHub Issues, providing:

    • Operating system and version

    • Error logs

    • Solutions already attempted