Introduction

Photogrammetry-CLI is a powerful command-line tool tailored for photogrammetry workflows. It facilitates the extraction of frames from video files, the generation of point clouds from images, and the combination of point clouds into a unified 3D model. Utilizing Meshroom's AliceVision for the photogrammetry process and CloudCompare for ICP alignment and mesh-to-cloud conversion, this tool is optimized for Windows, offering a streamlined solution for processing and analyzing 3D data derived from video sources.

Table of Contents

• Installation
  • Prerequisites
  • Source Code and Dependencies
  • Meshroom's AliceVision Setup
  • CloudCompare Setup
• Usage
• Commands
  • video2images
  • generatePointCloud
  • combinePointClouds
• License
• Authors

Installation

Prerequisites

• Operating System: Windows (only supported on Windows)
• Python Version: Python 3.11 (tested on this version but might work on other 3.x versions)
• Meshroom's AliceVision: Required for photogrammetry processing (refer to setup instructions below)
• CloudCompare: Required for ICP alignment and mesh-to-cloud conversion (refer to setup instructions below)
• GPU: NVIDIA GPU with CUDA support (recommended for optimal performance; absence of a CUDA-capable NVIDIA GPU might cause unexpected issues)

Source Code and Dependencies

To get started with the CLI, you need to clone the source code and install the required dependencies. Ensure that pip is installed and up to date before proceeding. Then, execute the following commands:

git clone --recursive https://github.com/noy-dayan/Photogrammetry-CLI.git
cd Photogrammetry-CLI
pip install -r requirements.txt

Meshroom's AliceVision Setup

1. Download Meshroom Zip File:

   • Download Meshroom from the following link:
     Meshroom v2023.3.0 for Windows 64-bit

2. Extract the Zip File:

   • Extract the contents of the zip file to a location of your choice.

3. Move the aliceVision Folder:

   • Locate the aliceVision folder inside the extracted Meshroom directory.
   • Drag the aliceVision folder to the root of the Photogrammetry-CLI directory.

4. Run Configuration Script:

   • Navigate to the project directory and run the configure.bat script with administrator privileges:

     configure.bat

   • This script will automatically configure the ALICEVISION_ROOT environment variable to point to the aliceVision folder.

CloudCompare Setup

1. Download CloudCompare Setup File:

   • Download CloudCompare from the following link:
     CloudCompare v2.13.2 for Windows 64-bit

2. Install CloudCompare:

   • Run the downloaded setup file and install CloudCompare to the following directory: C:\Program Files\CloudCompare

Usage

To start using the CLI, simply run the run.bat file or execute the run.py script directly. This will initiate the CLI and provide access to the available commands.

run.bat

Commands

video2images

Extracts frames from a video file based on structural similarity (SSIM) and overlap criteria.

Arguments:

• <video_path>: Path to the input video file (must be in .mp4 format).
• <project_path>: Path to the output folder where frames will be saved (a subfolder named images will be created).
• [max_frames] (optional): Maximum number of frames to extract (default is 100).
• [max_overlap_percentage] (optional): Maximum allowed percentage overlap with previous frames (default is 6).
• [ssim_threshold] (optional): SSIM threshold below which frames are considered different (default is 0.95).

Example:

video2images "path\\video.mp4" "path\\project\\dir" 200 5 0.90

generatePointCloud

Generates a point cloud from the extracted frames using the Meshroom's AliceVision photogrammetry pipeline.

Arguments:

• <project_path>: Path to the project folder containing the images folder.

Example:

generatePointCloud "path\\project\\dir"

combinePointClouds

Combines two point clouds into a single point cloud using the Iterative Closest Point (ICP) algorithm, assuming the point clouds are roughly aligned and have overlapping regions.

Arguments:

• <cloud1_path>: Path to the first point cloud file.
• <cloud2_path>: Path to the second point cloud file.
• <output_path>: Path to the cloud output file.
• [icp_iterations] (optional): Number of iterations for ICP alignment (default is 10,000).
• [icp_overlap] (optional): Overlap percentage for ICP (default is 40). Must be an integer between 10 and 100.

Example:

combinePointClouds "path\\cloud1.ply" "path\\cloud2.ply" "path\\output.ply" 5000 30

License

This project is licensed under the MIT License. See the LICENSE file for details.

Authors

• @noy-dayan (Project Manager)
• @AvivShevach
• @neryaRez