Package: optim3d
Optimized reconstruction of large-scale 3D building modelsCommand-Line Interface (CLI) application for efficient and optimized reconstruction of large-scale 3D building models.Optim3D is a powerful tool for optimized automatic reconstruction of highly detailed and large-scale 3D building models. Our tool is based on theGeoFlowsoftware and makes use of it to perform the 3D reconstruction of buildings. The process is inspired by the 3D BAG project and optimized for large-scale projects through indexing and tiling of the input data, which significantly reduces the processing time and resources required to generate large-scale 3D building models.DocumentationIf you are using Optim3D, we highly recommend that you take the time to read thedocumentation. 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.InstallationYou can install optim3d in your Conda environment by simply running:condacreate--nameoptimenvpython==3.6
condaactivateoptimenv
condainstall-cconda-forgepdalpython-pdal
condainstall-cconda-forgeentwine
pipinstalloptim3dYou can also build everything from source (seeINSTALL.md). ADocker imageis also available.NOTE:It is important to note that in order to use our program for 3D reconstruction of buildings,GeoFlow-bundlemust be installed. Please read the LICENSE file.Usage of the CLIPython packageAfter installation, you have a small program calledoptim3d. Useoptim3d --helpto 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 orcommandsthat must be executed in a specific order to achieve the desired outcome.Step 1 : 2D building footprints indexing and tilingQuadtree-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 commandindex2d. Useoptim3d index2d --helpto 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.Step 2 : OcTree indexing of the 3D point cloudProcessing 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 commandindex3d. Useoptim3d index3d --helpto 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.Step 3 : Tiling of the 3D point cloudThe tiling of the indexed point cloud is based on the processing areas already calculated. This is achieved using the third commandtiler3d. Useoptim3d tiler3d --helpto 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.Step 4 : 3D reconstruction of building models tile by tileIn 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 commandreconstruct. Useoptim3d reconstruct --helpto 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.Step 5 : Post-processing of CityJSON filesThe generated CityJSON files should be post-processed to correct the City Objects IDs. This is done using the fifth commandpost. Useoptim3d post --helpto 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.Docker ImageOptim3D is also available asDocker image. If you are using a Windows operating system, we recommend running the Docker container inside the Windows Subsystem for Linux 2 (WSL2) environment. Please ensure that Geoflow is installed on the WSL2 environment to ensure compatibility with the container.These are the steps to run Optim3D as a Docker container:First pull the image using thedocker pullcommand:dockerpullyarroudh/optim3dTo run the Docker container and mount your data inside it, use thedocker 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:dockerrun-d-vABSOLUTE_PATH_TO_HOST_DATA:/home/user/datayarroudh/optim3dThis command will start a Docker container in detached mode, mount theABSOLUTE_PATH_TO_HOST_DATAdirectory on the host machine to the/home/user/datadirectory inside the container, and run theyarroudh/optim3dimage. Do not change the path of the directory inside the container.Find the container ID and copy it. You can use thedocker pscommand to list all running containers and their IDs.Launch a command inside the container usingdocker exec, use the container ID or name and the command you want to run. For example:dockerexecCONTAINER_IDoptim3dindex2ddata/FILE_NAMEThis command will execute the QuadTree indexing of the 2D footprints data, which can be a Shapefile (.shp) or a GeoPackage (.gpkg).For thereconstructcommand, make sure to copy Geoflow-bundle folder to the$PATHenvironment variable of the container before running the reconstruction:dockercpPATH_TO_GEOFLOW_BUNDLECONTAINER_ID:$PATHdockerexecCONTAINER_IDoptim3dreconstructTo copy the output of the command from the container to a local path, use thedocker 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:dockercpCONTAINER_ID:/home/user/output/footprint_tilesPATH_ON_HOST_MACHINETop copy the output of all the commands:dockercpCONTAINER_ID:/home/user/outputPATH_ON_HOST_MACHINEFinally, after executing all the commands and copying the results to your local machine, you can stop the Docker container using thedocker stopcommand followed by the container ID or name:dockerstopCONTAINER_IDBuilding from sourceIf you want to build the solution from source, you should follow the steps inINSTALL.md.ResultsThe results of each command are saved in theoutputfolder 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 usingNinja, the official web viewer for CityJSON files.Related repositoriesAutomatic correction of buildings ground floor elevation in 3D City ModelsGeoFlow 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 usingZRect3D, a tool for automatic correction of buildings ground-floor elevation in CityJSON files using ground points from LiDAR data.LicenseThis 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 theLICENSEand theCOPYINGfiles for more details.CitationThe use of open-source software repositories has become increasingly prevalent in scientific research. If you use this repository for your research, please make sure to cite it appropriately in your work. The recommended citation format for this repository is provided in the accompanyingBibTeX citation. Additionally, please make sure to comply with any licensing terms and conditions associated with the use of this repository.@misc{yarroudh:2023:optim3d,author={Yarroudh, Anass},title={Optim3D: Optimized reconstruction of large-scale 3D building models},year={2023},howpublished={GitHub Repository},url={https://github.com/Yarroudh/Optim3D}}Yarroudh, A. (2023). Optim3D: Optimized reconstruction of large-scale 3D building models [GitHub repository]. Retrieved fromhttps://github.com/Yarroudh/Optim3DAbout Optim3DThis software was developped byAnass Yarroudh, a Research Engineer in theGeomatics Unit of the University of Liege.
For more detailed information please contact us viaayarroudh@uliege.be, we are pleased to send you the necessary information.