### Install dependencies on Ubuntu/Debian

Source: https://tudelft3d.github.io/3dfier/installation.html

Install all required dependencies for 3dfier on Ubuntu 22.04 (jammy) using apt-get.

```bash
sudo apt-get update
sudo apt-get install -y cmake g++ make \
  libboost-program-options-dev libboost-filesystem-dev \
  libboost-locale-dev libboost-chrono-dev \
  libcgal-dev libgdal-dev libpdal-dev libyaml-cpp-dev
```

--------------------------------

### Run 3dfier without arguments to test installation

Source: https://tudelft3d.github.io/3dfier/generate_lod1.html

Run './3dfier' to verify the installation. The expected output shows the program banner and an error indicating that a YAML config file must be specified, followed by the list of allowed output options.

```bash
$ ./3dfier 
3dfier Copyright (C) 2015-2019  3D geoinformation research group, TU Delft
This program comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions; for details run 3dfier with the '--license' option.

ERROR: one YAML config file must be specified.

Allowed options:
  --help                        View all options
  --version                     View version
  --license                     View license
  --OBJ arg                     Output
  --OBJ-NoID arg                Output
  --CityGML arg                 Output
  --CityGML-Multifile arg       Output
  --CityGML-IMGeo arg           Output
  --CityGML-IMGeo-Multifile arg Output
  --CityJSON arg                Output
  --CSV-BUILDINGS arg           Output
  --CSV-BUILDINGS-MULTIPLE arg  Output
  --CSV-BUILDINGS-ALL-Z arg     Output
  --Shapefile arg               Output
  --Shapefile-Multifile arg     Output
  --PostGIS arg                 Output
  --PostGIS-PDOK arg            Output
  --PostGIS-PDOK-CityGML arg    Output
  --GDAL arg                    Output
```

--------------------------------

### Run 3dfier with example data

Source: https://tudelft3d.github.io/3dfier/first_run.html

Navigate to the example_data folder and run 3dfier with the testarea_config.yml configuration file, outputting an OBJ file. The command is `..\3dfier.exe testarea_config.yml --OBJ output\myfirstmodel.obj`. The output file is written to `example_data\output\myfirstmodel.obj`.

```bash
cd example_data
..\3dfier.exe testarea_config.yml --OBJ output\myfirstmodel.obj
```

--------------------------------

### Install dependencies on macOS with Homebrew

Source: https://tudelft3d.github.io/3dfier/installation.html

Use Homebrew to install all required dependencies for compiling 3dfier on macOS.

```bash
$ brew install boost cgal gdal pdal yaml-cpp cmake
```

--------------------------------

### Generate 3D model with 3dfier command line

Source: https://tudelft3d.github.io/3dfier/generate_lod1.html

Runs 3dfier with the configuration file and outputs both OBJ and CityJSON files. The process should take less than half a minute for the example data.

```bash
3dfier testarea_config.yml --OBJ output/testarea.obj --CityJSON output/testarea.json
```

--------------------------------

### OBJ output example with material-based semantic labelling

Source: https://tudelft3d.github.io/3dfier/output_flow.html

Shows the OBJ output format for a building object. Objects are written as MultiSurface, and semantic labelling is achieved by defining a material (usemtl Terrain) as a work-around. The example includes an object ID and face definitions.

```obj
o b222b6a92-00b5-11e6-b420-2bdcc4ab5d7f
usemtl Terrain
f 2596 2597 2598
f 2598 2599 2600
f 2597 2601 2602
```

--------------------------------

### Compile 3dfier on macOS

Source: https://tudelft3d.github.io/3dfier/installation.html

Commands to build and install 3dfier from source on macOS.

```bash
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make
$ make install
```

--------------------------------

### Configure input elevation datasets in testarea_config.yml

Source: https://tudelft3d.github.io/3dfier/generate_lod1.html

Specifies the input point cloud files (AHN3) and optional settings to omit LAS classes and thin points. The example uses two LAZ files and omits class 1 (unclassified) with no thinning.

```yaml
input_elevation:
  - datasets:
      - ahn3/ahn3_cropped_1.laz
      - ahn3/ahn3_cropped_2.laz
    omit_LAS_classes:
      - 1 # unclassified
    thinning: 0
```

--------------------------------

### Define a single LAS/LAZ file in datasets

Source: https://tudelft3d.github.io/3dfier/input_options.html

Configure a single point cloud file in the datasets section. The filename must be indented deeper than the datasets key, and each dataset and file starts with a leading dash.

```yaml
- datasets:                         # List of data set with specific settings
  - D:\data\top10nl\schie\ahn3.laz  # Definition for one or multiple LAS/LAZ files using the same parameters
```

--------------------------------

### Example YAML input configuration for 3dfier

Source: https://tudelft3d.github.io/3dfier/generate_lod1.html

Shows a minimal YAML configuration for defining input polygons from a 2D dataset (e.g., building footprints). The 'uniqueid' field specifies the attribute used as unique identifier, and 'lifting' defines the type of reconstruction (here 'Building').

```yaml
input_polygons:
    datasets: 
      - bgt/bgt_pand.sqlite
    uniqueid: gml_id
    lifting: Building
```

--------------------------------

### Expected console output from 3dfier run

Source: https://tudelft3d.github.io/3dfier/first_run.html

Console output after running 3dfier with the example data. It shows the license notice, configuration validation, reading of input datasets, processing steps, and successful termination. The output ends with 'Successfully terminated in 2 seconds || 00:00:02'.

```text
3dfier Copyright (C) 2015-2019  3D geoinformation research group, TU Delft
This program comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions; for details run 3dfier with the '--license' option.

Config file is valid.
Reading input dataset: bgt\bgt_waterdeel.sqlite
        Layer: waterdeel
        (3 features --> Water)
Reading input dataset: bgt\bgt_ondersteunendwaterdeel.sqlite
        Layer: ondersteunendwaterdeel
        (0 features --> Water)
Reading input dataset: bgt\bgt_onbegroeidterreindeel.sqlite
        Layer: onbegroeidterreindeel
        (81 features --> Terrain)
Reading input dataset: bgt\bgt_wegdeel.sqlite
        Layer: trafficarea
        (151 features --> Road)
Reading input dataset: bgt\bgt_ondersteunendwegdeel.sqlite
        Layer: auxiliarytrafficarea
        (0 features --> Road)
Reading input dataset: bgt\bgt_pand.sqlite
        Layer: buildingpart
        (160 features --> Building)
Reading input dataset: bgt\bgt_begroeidterreindeel.sqlite
        Layer: plantcover
        (126 features --> Forest)
Reading input dataset: bgt\bgt_scheiding.sqlite
        Layer: scheiding
        (57 features --> Separation)
Reading input dataset: bgt\bgt_kunstwerkdeel.sqlite
        Layer: kunstwerkdeel
        (1 features --> Separation)
Reading input dataset: bgt\bgt_overigbouwwerk.sqlite
        Layer: overigbouwwerk
        (0 features --> Separation)
Reading input dataset: bgt\bgt_overbruggingsdeel.sqlite
        Layer: bridgeconstructionelement
        (3 features --> Bridge/Overpass)

Total # of polygons: 570
Constructing the R-tree... done.
Spatial extent: (84,616.468, 447,422.999) (85,140.839, 447,750.636)
Reading LAS/LAZ file: ahn3\ahn3_cropped_1.laz
        (640,510 points in the file)
        (all points used, no skipping)
        (omitting LAS classes: 0 1 )
[==================================================] 100%
Reading LAS/LAZ file: ahn3\ahn3_cropped_2.laz
        (208,432 points in the file)
        (all points used, no skipping)
        (omitting LAS classes: 0 1 )
[==================================================] 100%
All points read in 1 seconds || 00:00:01
3dfying all input polygons...
===== /LIFTING =====
===== LIFTING/ =====
=====  /ADJACENT FEATURES =====
=====  ADJACENT FEATURES/ =====
=====  /STITCHING =====
=====  STITCHING/ =====
=====  /BOWTIES =====
=====  BOWTIES/ =====
=====  /VERTICAL WALLS =====
=====  VERTICAL WALLS/ =====
Lifting, stitching and vertical walls done in 0 seconds || 00:00:00
=====  /CDT =====
=====  CDT/ =====
CDT created in 0 seconds || 00:00:00
...3dfying done.
OBJ output: output\myfirstmodel.obj
Features written in 0 seconds || 00:00:00
Successfully terminated in 2 seconds || 00:00:02
```

--------------------------------

### All objects configuration

Source: https://tudelft3d.github.io/3dfier/minimal_data_requirements.html

Configuration for creating a 3D model with all objects in an area. Requires topologically connected polygons and a point cloud with ground/non-ground classification. Ground-like objects use only ground points (class 2), while others use all points.

```yaml
input_polygons:
  - datasets: 
      - bgt\bgt_waterdeel.sqlite
      - bgt\bgt_ondersteunendwaterdeel.sqlite
    uniqueid: gml_id
    lifting: Water
    height_field: relatievehoogteligging
  - datasets: 
      - bgt\bgt_onbegroeidterreindeel.sqlite
    uniqueid: gml_id
    lifting: Terrain
    height_field: relatievehoogteligging
  - datasets: 
      - bgt\bgt_wegdeel.sqlite
      - bgt\bgt_ondersteunendwegdeel.sqlite
    uniqueid: gml_id
    lifting: Road
    height_field: relatievehoogteligging
  - datasets: 
      - bgt\bgt_pand.sqlite
    uniqueid: gml_id
    lifting: Building
    height_field: relatievehoogteligging
  - datasets: 
      - bgt\bgt_begroeidterreindeel.sqlite
    uniqueid: gml_id
    lifting: Forest
    height_field: relatievehoogteligging
  - datasets: 
      - bgt\bgt_scheiding.sqlite
      - bgt\bgt_kunstwerkdeel.sqlite
      - bgt\bgt_overigbouwwerk.sqlite
    uniqueid: gml_id
    lifting: Separation
    height_field: relatievehoogteligging
  - datasets: 
      - bgt\bgt_overbruggingsdeel.sqlite
    uniqueid: gml_id
    lifting: Bridge/Overpass
    height_field: relatievehoogteligging

lifting_options: 
  Building:
    ground:
      height: percentile-10
      use_LAS_classes:
        - 2
    roof:
      height: percentile-90
  Terrain:
    simplification_tinsimp: 0.1
    use_LAS_classes:
      - 2
  Forest:
    simplification_tinsimp: 0.1
    use_LAS_classes:
      - 2
  Water:
    height: percentile-10
  Road:
    height: percentile-50
    use_LAS_classes:
      - 2
  Separation:
    height: percentile-80
  Bridge\Overpass:
    height: percentile-50

input_elevation:
  - datasets:
      - ahn3\ahn3_cropped_1.laz
      - ahn3\ahn3_cropped_2.laz
```

--------------------------------

### Compile 3dfier on Windows with vcpkg

Source: https://tudelft3d.github.io/3dfier/installation.html

Recommended way to compile 3dfier on Windows using vcpkg. Dependencies are described in the vcpkg.json manifest.

```bash
git clone https://github.com/tudelft3d/3dfier.git
cd 3dfier
vcpkg install
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="C:\vcpkg\scripts\buildsystems\vcpkg.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
```

--------------------------------

### Build and develop with Nix flake

Source: https://tudelft3d.github.io/3dfier/installation.html

Use the provided Nix flake to build 3dfier on Linux and macOS, and to enter a development shell.

```bash
nix build
nix develop
```

--------------------------------

### Compile 3dfier on Ubuntu/Debian

Source: https://tudelft3d.github.io/3dfier/installation.html

Clone the repository and compile 3dfier on Ubuntu/Debian. Note that newer Ubuntu (24.04) and Debian (12+) do not ship the pdal package.

```bash
git clone https://github.com/tudelft3d/3dfier.git
cd 3dfier; mkdir build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make
sudo make install
```

--------------------------------

### Read all LAS/LAZ files in a directory using wildcard

Source: https://tudelft3d.github.io/3dfier/input_options.html

Use an asterisk (*) instead of a filename to read all files in a directory. There is no file extension check, so the directory should contain only LAS/LAZ files.

```yaml
- datasets:                         # List of data set with specific settings
  - D:\data\top10nl\schie\*         # Definition for reading a full directory with LAS/LAZ files using the same parameters
```

--------------------------------

### Configure building lifting options in testarea_config.yml

Source: https://tudelft3d.github.io/3dfier/generate_lod1.html

Sets the roof and ground elevation percentiles for building footprints. The roof uses the 90th percentile and the ground uses the 10th percentile to filter outliers.

```yaml
lifting_options:
  Building:
    roof:
        height: percentile-90
    ground:
        height: percentile-10
```

--------------------------------

### Nested dataset configuration for multi-layer files

Source: https://tudelft3d.github.io/3dfier/input_options.html

Alternative configuration for files with multiple layers, such as GML. Maps each layer name to a lifting class using the lifting_per_layer option.

```yaml
- datasets:
  - D:\data\campus\polygons.gml
 uniqueid: fid
 lifting_per_layer:
     Buildingfootprint: Building
     Terrainobjects: Terrain
     Waterways: Water

```

--------------------------------

### 3dfier command-line output when no config file is specified

Source: https://tudelft3d.github.io/3dfier/first_run.html

Expected output when running 3dfier without a YAML config file. It shows the copyright notice, warranty disclaimer, and an error indicating that one YAML config file must be specified, followed by the list of allowed output options.

```text
3dfier Copyright (C) 2015-2019  3D geoinformation research group, TU Delft
This program comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions; for details run 3dfier with the '--license' option.

ERROR: one YAML config file must be specified.

Allowed options:
  --help                        View all options
  --version                     View version
  --license                     View license
  --OBJ arg                     Output
  --OBJ-NoID arg                Output
  --CityGML arg                 Output
  --CityGML-Multifile arg       Output
  --CityGML-IMGeo arg           Output
  --CityGML-IMGeo-Multifile arg Output
  --CityJSON arg                Output
  --CSV-BUILDINGS arg           Output
  --CSV-BUILDINGS-MULTIPLE arg  Output
  --CSV-BUILDINGS-ALL-Z arg     Output
  --Shapefile arg               Output
  --Shapefile-Multifile arg     Output
  --PostGIS arg                 Output
  --PostGIS-PDOK arg            Output
  --PostGIS-PDOK-CityGML arg    Output
  --GDAL arg                    Output

```

--------------------------------

### Building lifting options YAML configuration

Source: https://tudelft3d.github.io/3dfier/lifting_options.html

YAML configuration for the Building class in lifting_options. Defines roof and ground height percentiles, LAS classes to use, LoD, and flags for floors, inner walls, and triangulation. If a class is not defined, default values from resources/config_files/myconfig_DEFAULTS.yml are used.

```yaml
roof:
 height: percentile-90     # Percentile of points within radius of building vertices for roof height lifting, building_radius_vertex_elevation is defined in options
 use_LAS_classes:          # LAS classes to be used for this class. If empty all classes are used
   - 6
ground:
 height: percentile-10     # Percentile of points within radius of building vertices for floor height lifting
 use_LAS_classes:
   - 2
   - 9
lod: 1                      # Define the Level Of Detail for Buildings (0 and 1 possible)
floor: true                 # Set if floors should be created
inner_walls: true           # Set if the walls between to adjacent buildings within a block should be created
triangulate: false          # Set if the output should be triangulated, only works for non-triangular output formats like CityGML/IMGeo
```

--------------------------------

### PostGIS output command with connection string

Source: https://tudelft3d.github.io/3dfier/supported_file_formats.html

Use this command to output to a PostGIS database. The connection string must be double quoted to be passed as a single parameter. The PostGIS specifier creates a table per layer, a column per attribute, and a geometry column of type MultiPolygonZ.

```bash
3dfier example_data\testarea_config.yml --PostGIS "PG:dbname='3dfier' host='localhost' port='5432' user='username' password='password'"
```

--------------------------------

### GDAL driver configuration in YAML

Source: https://tudelft3d.github.io/3dfier/supported_file_formats.html

Configure the generic GDAL output driver by adding a new section in the configuration file. The driver must support creation of geometries and MultiPolygonZ.

```yaml
output:
  gdal_driver: "ESRI Shapefile"
```