Paper is now published. For more information, please refer to: Recent Advances in 3D Geoinformation Science
Command-Line Interface (CLI) application for efficient and optimized reconstruction of large-scale 3D building models.
Optim3D is a powerful tool for efficient and scalable generation of highly detailed and large-scale 3D building models. The modeling process is based on GeoFlow. The tool focuses mainly on preparing data for efficient reconstruction through indexing, tiling and parallel computing, which significantly reduces the processing time and resources required to generate large-scale 3D building models.
If you are using Optim3D, we highly recommend that you take the time to read the documentation. The documentation is an essential resource that will help you understand the features and functionality of our software, as well as provide guidance on how to use it effectively.
You can install optim3d in your Conda environment by simply running:
conda create --name optimenv python==3.6
conda activate optimenv
conda install -c conda-forge pdal python-pdal
conda install -c conda-forge entwine
pip install optim3dYou can also build everything from source (see INSTALL.md). A Docker image is also available.
NOTE: It is important to note that in order to use our program for 3D reconstruction of buildings, GeoFlow-bundle must be installed. Please read the LICENSE file.
After installation, you have a small program called optim3d. Use optim3d --help to see the detailed help:
Usage: optim3d [OPTIONS] COMMAND [ARGS]...
CLI tool to manage full optimized reconstruction of large-scale 3D
building models.
Options:
--help Show this message and exit.
Commands:
index2d QuadTree indexing and tiling of 2D building footprints.
index3d OcTree indexing of 3D point cloud using Entwine.
tiler3d Tiling of point cloud using the calculated processing areas.
reconstruct Optimized 3D reconstruction of buildings using GeoFlow.
post Post-processing generated CityJSON files.
The process consists of five steps or commands that must be executed in a specific order to achieve the desired outcome.
Quadtree-based tiling scheme is used for spatial partitioning of building footprints. This assures that the reconstruction time per tile is more or less the same and that the tiles available for download are similar in file size. This is done using the first command index2d. Use optim3d index2d --help to see the detailed help:
Usage: optim3d index2d [OPTIONS] [FOOTPRINTS]
QuadTree indexing and tiling of building 2D footprints.
Options:
--output PATH Output directory. [default: ./output]
--osm <FLOAT FLOAT FLOAT FLOAT>...
Download and work with building footprints
from OpenStreetMap [west, north, est,
south].
--crs INTEGER Specify the Coordinate Reference System
(EPSG).
--max INTEGER Maximum number of buildings per tile.
[default: 3500]
--help Show this message and exit.
Processing large point cloud datasets is hardware-intensive. Therefore, it is necessary to index the 3D point cloud before processing. The index structure makes it possible to stream only the parts of the data that are required, without having to download the entire dataset. In this case, the spatial indexing of the airborne point cloud is performed using an octree structure. This is done using the second command index3d. Use optim3d index3d --help to see the detailed help:
Usage: optim3d index3d [OPTIONS] POINTCLOUD
OcTree indexing of 3D point cloud using Entwine.
Options:
--output PATH Output directory. [default: ./output]
--help Show this message and exit.
The tiling of the indexed point cloud is based on the processing areas already calculated. This is achieved using the third command tiler3d. Use optim3d tiler3d --help to see the detailed help:
Usage: optim3d tiler3d [OPTIONS]
Tiling of 3D point cloud using the calculated processing areas.
Options:
--areas PATH The calculated processing areas. [default:
./output/processing_areas.gpkg]
--indexed PATH Indexed 3D point cloud directory. [default:
./output/indexed_pointcloud]
--output PATH Output directory. [default: ./output]
--help Show this message and exit.
In this step, we perform the 3D reconstruction of building models. The process make use of GeoFlow to generate highly detailed 3D building models tile by tile. This is achieved using the fourth command reconstruct. Use optim3d reconstruct --help to see the detailed help:
Usage: optim3d reconstruct [OPTIONS]
Optimized 3D reconstruction of buildings using GeoFlow.
Options:
--pointcloud PATH 3D point cloud tiles directory. [default:
./output/pointcloud_tiles]
--footprints PATH 2D building footprints tiles directory. [default:
./output/footprint_tiles]
--output PATH Output directory. [default: ./output]
--help Show this message and exit.
The generated CityJSON files should be post-processed to correct the City Objects IDs. This is done using the fifth command post. Use optim3d post --help to see the detailed help:
Usage: optim3d post [OPTIONS]
Postprocess the generated CityJSON files.
Options:
--cityjson PATH CityJSON files directory. [default:
./output/model/cityjson]
--help Show this message and exit.
Optim3D is also available as Docker image.
These are the steps to run Optim3D as a Docker container:
- First pull the image using the
docker pullcommand:
docker pull yarroudh/optim3d- To run the Docker container and mount your data inside it, use the
docker runcommand with the-voption to specify the path to the host directory and the path to the container directory where you want to mount the data folder. For example:
docker run -d -v ABSOLUTE_PATH_TO_HOST_DATA:/home/user/data yarroudh/optim3dThis command will start a Docker container in detached mode, mount the ABSOLUTE_PATH_TO_HOST_DATA directory on the host machine to the /home/user/data directory inside the container, and run the yarroudh/optim3d image. Do not change the path of the directory inside the container.
- Find the container ID and copy it. You can use the
docker pscommand to list all running containers and their IDs. - Launch a command inside the container using
docker exec, use the container ID or name and the command you want to run. For example:
docker exec CONTAINER_ID optim3d index2d data/FILE_NAME
docker exec CONTAINER_ID optim3d index3d data/FILE_NAME
docker exec CONTAINER_ID optim3d tiler3d
docker exec CONTAINER_ID optim3d reconstruct
docker exec CONTAINER_ID optim3d post- To copy the output of the command from the container to a local path, use the
docker cpcommand with the container ID or name, the path to the file inside the container, and the path to the destination on the host machine. For example:
- To copy the output of one command:
docker cp CONTAINER_ID:/home/user/output/footprint_tiles PATH_ON_HOST_MACHINEThis will copy the output of footprints tiling. Please check the results section for the output structure.
- To copy the output of all the commands:
docker cp CONTAINER_ID:/home/user/output PATH_ON_HOST_MACHINE- Finally, after executing all the commands and copying the results to your local machine, you can stop the Docker container using the
docker stopcommand followed by the container ID or name:
docker stop CONTAINER_IDIf you want to build the solution from source, you should follow the steps in INSTALL.md.
The results of each command are saved in the output folder with the following structure:
├── output
│ ├── flowcharts
│ │ ├── *.json
│ ├── footprint_tiles
│ │ ├── *.cpg
│ │ ├── *.dbf
│ │ ├── *.prj
│ │ ├── *.shp
│ │ ├── *.shx
│ ├── indexed_pointcloud
│ │ ├── ept-data
│ │ │ ├── *.laz
│ │ ├── ept-hierarchy
│ │ │ ├── 0-0-0-0.json
│ │ ├── ept-sources
│ │ │ ├── *.json
│ │ ├── ept.json
│ │ ├── ept-build.json
│ ├── model
│ │ ├── cityjson
│ │ ├── *.city.json
│ │ ├── obj
│ │ ├── *.obj
│ │ ├── *.obj.mtl
│ ├── pointcloud_tiles
│ │ ├── *.las
│ ├── processing_areas.gpkg
│ └── quadtree.gpkgThe 3D building models can be inspected using Ninja, the official web viewer for CityJSON files.
Automatic correction of buildings ground floor elevation in 3D City Models
GeoFlow requires that the point cloud includes some ground points around the building so that it can determine the ground floor elevation. However, for aerial point clouds, buildings surrounded by others may not meet this condition which may result in inaccurate height estimation above the ground. This can be resolved using ZRect3D, a tool for automatic correction of buildings ground-floor elevation in CityJSON files using ground points from LiDAR data.
This software is under the BSD 3-Clause "New" or "Revised" license which is a permissive license that allows you almost unlimited freedom with the software so long as you include the BSD copyright and license notice in it. Please read the LICENSE and the COPYING files for more details.
The recommended citation format for this repository is provided in the accompanying BibTeX citation. Additionally, please make sure to comply with any licensing terms and conditions associated with the use of this repository.
@InProceedings{10.1007/978-3-031-43699-4_50,
author="Yarroudh, Anass
and Kharroubi, Abderrazzaq
and Billen, Roland",
editor="Kolbe, Thomas H.
and Donaubauer, Andreas
and Beil, Christof",
title="Optim3D: Efficient and Scalable Generation of Large-Scale 3D Building Models",
booktitle="Recent Advances in 3D Geoinformation Science",
year="2024",
publisher="Springer Nature Switzerland",
address="Cham",
pages="835--849",
}Yarroudh, A., Kharroubi, A., Billen, R. (2024). Optim3D: Efficient and Scalable Generation of Large-Scale 3D Building Models. In: Kolbe, T.H., Donaubauer, A., Beil, C. (eds) Recent Advances in 3D Geoinformation Science. 3DGeoInfo 2023. Lecture Notes in Geoinformation and Cartography. Springer, Cham. https://doi.org/10.1007/978-3-031-43699-4_50
This software was developped by Anass Yarroudh, Research Engineer in the GeoScITY department of the University of Liege. For more detailed information please contact us via ayarroudh@uliege.be, we are pleased to send you the necessary information.