Skip to content

Preparation before the tutorial

Installation and Download

In this tutorial, we will use

  • the py4dgeo library for change analysis in 4D point clouds;
  • CloudCompare, a popular point cloud data processing software, which we will use for visualisation.

Start by downloading the data and code. If you have any questions or problems with installation, please contact:

Dataset and Code

To make the setup process as smooth as possible, we have bundled the Jupyter notebooks and the datasets together into a single, ready-to-run archive.

Use the download link to download the all-in-one package. After downloading, extract the archive to a local folder where you have write access.

Running the Notebooks: For beginners, we recommend using Jupyter Lab as it requires no additional IDE installation. However, if you are already familiar with IDEs like VS Code, PyCharm, or others, you can simply open the extracted folder in your editor and run the .ipynb notebooks directly from there.

Your local course folder structure will look something like this:

course_bundle/
  notebooks/
    activity-2_1.ipynb
    activity-3_1.ipynb
    ...
  data/
    activity_2/point_clouds/
    activity_3_1_and_3_3/point_clouds/
    activity_3_2/point_clouds/
  assets/
    figures_for_notebooks

Mamba

💡 Note for experienced users: We recommend mamba for its speed and efficiency. However, if you already have conda (Anaconda/Miniconda) or another environment manager installed, you do not need to install mamba. You can simply skip this step and replace mamba with conda in all the following terminal commands.

Mamba is a fast, robust, and cross-platform package manager. As recommended by the developers, we will install Mamba through the Miniforge distribution. Follow the instructions from this page: Mamba Installation. We provide a short summary below.

Here is the direct link to the Windows installer: https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe. Follow the prompts, taking note of the option to "Create start menu shortcuts".

For installation on Unix-like platforms, follow the instructions at: https://github.com/conda-forge/miniforge?tab=readme-ov-file#unix-like-platforms-macos-linux--wsl.

Setting up py4dgeo (for user only)

For the purpose of this tutorial, the following setup is sufficient. To create a Mamba environment with the necessary libraries, follow these steps:

  1. Open a terminal (Miniforge Prompt on Windows, Terminal on macOS/Linux).

  2. Create a new mamba environment named py4dgeo_env with Python version >=3.10 and py4dgeo:

    mamba create -n py4dgeo_env python=3.12 -c conda-forge

    This might take a few minutes (for lower end devices up to 20 minutes) as mamba resolves dependencies and downloads the required packages. Just be patient and wait.

  3. Close Miniforge. Reopen the Miniforge prompt and activate the newly created environment by typing: 

    mamba activate py4dgeo_env
python -m pip install py4dgeo
mamba install -c conda-forge jupyterlab ipykernel jupyter tqdm ipywidgets

  4. Navigate to the course_bundle folder you extracted earlier using your terminal: 

    cd "path/to/your/course_bundle"

  5. Start Jupyter Lab from within this folder: 

    jupyter-lab

  6. In Jupyter Lab, use the file browser on the left to open the notebooks/ folder. Here, you will find all the .ipynb files required for the tutorial. Start with:

    • activity-2_1-installation-recap.ipynb
    • activity-2_2-standard-workflow.ipynb
    • activity-2_3-coregistration.ipynb
    • activity-2_4-many-point-clouds.ipynb
    • activity-2_5-time-series.ipynb
    • activity-3_1-deformation-monitoring.ipynb
    • activity-3_2-urban-scene-changes.ipynb
    • activity-3_3-screening-relevant-and-non-relevant-changes.ipynb

The Notebooks section on this website shows rendered previews of the same notebooks. To run the code, open the .ipynb files in Jupyter Lab.

Setting up py4dgeo (for developer and potential contributor)

For developers and potential contributors who want to build py4dgeo from source: if you want to contribute to the library's development, such as new methods that extend py4dgeo's analytical capabilities, or usage examples and application demos that illustrate how to apply existing or new methods, then building from source is the right approach for you. For details on how to contribute, please refer to our Contributing Guidelines.

CloudCompare

CloudCompare is a widely used point cloud processing software. It allows to intuitively visualize 3D point clouds.

Troubleshooting

  • Issue when trying to activate the environment:
critical libmamba Shell not initialized

'mamba' is running as a subprocess and can't modify the parent shell.
 Thus you must initialize your shell before using activate and deactivate.
  • Solution: Close and reopen the Miniforge prompt and try again.

Further information (advanced)

Git repository

This website is hosted on GitHub: https://github.com/3dgeo-heidelberg/py4dgeo-tutorial

If you are an advanced user and prefer to clone the raw repository using git instead of downloading the pre-packaged bundle, you can do so: 

git clone https://github.com/3dgeo-heidelberg/py4dgeo-tutorial.git

Useful terminal commands

  • To navigate between folders use cd (change directory): cd "C:\my folder\my sub-folder" ATTENTION: if your folders or files contain spaces, you should use quotation marks " ".

  • To list existing environments : mamba env list

  • To activate an environment : mamba activate __my_environment__ (in our case: mamba activate py4dgeo_env)

  • To open Jupyter notebooks : jupyter-lab __my_notebook__.ipynb

  • To list dependencies once you are in an active environment: mamba list

  • ... something is missing - we can add it on the go (provided that we're inside an active environment) : mamba install __my_package__

Additional resources

For more information using mamba and conda, you can refer to the following resources: