Environment Setup - radiantlab/HDRICalibrationTool GitHub Wiki

This page will guide you to running our application starting from cloning the repository. It is intended for users who wish to modify the source code and tells them how they can build the same environment and re-bundle the application.

We will guide you through these steps:

  1. Cloning the repository
  2. Setting up the Python Environment (venv setup and installing dependencies)
  3. Bundling with PyInstaller

Once the above steps have been completed, you can find an executable called "HDRICalibrationTool-windows.exe". Double-click this to run, and the app should launch alongside a terminal window where output will be redirected!

[IMPORTANT] Prerequisites for use

As of v1.0.0, Windows users must have:

Note: Any directory that is a parent to the tool's cloned repository must not contain any space characters.

1. Cloning the repository

See the official GitHub documentation for cloning a repository here:

https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository

They have nice image examples to show you how to get our code.

After cloining our repository, you should have a directory somewhere on your machine called '\HDRICalibrationTool'. This is the root-level directory of the app repository.

Note: Any directory that is a parent to the tool's cloned repository must not contain any space characters.

Alternatively, you could download a .zip of our repository, in the same "Code" drop-down menu where you get the URL to clone the repository.

1a. Cloning the radiance_pipeline submodule

Our app is separated into a frontend interface (this HDRICalibrationTool repository) and a backend that hooks into Radiance (see: https://github.com/zimmermannliam/radiance_pipeline).

You will need to also obtain the submodule files to successfully build and run our application.

If you have already cloned our repository, you can open a terminal and type the following command (assuming Git is installed):

git submodule init

Followed by this command:

git submodule update

You can check the directory at '~\HDRICalibrationTool\submodules\radiance_pipeline' to see if is empty (bad) or if there are files in it (good).

Alternatively, if you have yet to clone our repository yet, you can get both in one 'git clone' step using the following command:

git clone --recursive https://github.com/thisRepo.git FOLDER_NAME

Using this command, this repository, along with the radiance_pipeline repository will be cloned into FOLDER_NAME destination directory on your machine.

2. Setting up the environment

This app uses Python 3's built-in virtual environment library 'venv'. It is recommended to build our app in a virtual environment so that you can ensure the app will run as tested.

This is a brief tutorial, and for more information see the official Python docs here for more details and troubleshooting: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/

2a. Creating your virtual environment

Using Windows the Command Prompt or PowerShell terminal, navigate to the root of the cloned repository [^1] (ex: C:\Users\UserName\Desktop\HDRICalibrationTool) and run the following command:

{Path-to-Python-3.11.1}\Python -m venv env

  • For example, if you installed Python 3.11.1 to the directory 'C:\Python311', you would run the following command:

    • C:\Python311\Python -m venv env

This will create a virtual environment called 'env' in the current directory the terminal is running using the specific 3.11 version of Python.

Next, to enter (or 'activate', as Python calls it) your virtual environment, run the following command:

.\env\Scripts\activate

To double-check you are in your virtual environment at this point, you should now see '(env)' in your terminal before your current working directory path.

To leave the virtual environment 'env', run the command deactivate in your Windows terminal.

Creating a virtual environment installs the Python package installer 'pip' for you. This will be necessary to install the dependencies as described in the next section.

[^1]: A nice shortcut I like to do on Windows is type in 'cmd' (or, 'powershell' works too) into the search bar of the Windows File Explorer in the directory I want to open a Command Prompt terminal in.

2b. Installing dependencies

Now, we can install the dependencies that the app needs to run. All of the minimum modules are already listed and stored in a .txt file in the root directory at \HDRICalibrationTool\requirements.txt.

To easily have Python automatically install these specific modules and the specific versions we tested on, run the following command while you are inside of your Python 3.11.1 virtual environment you created above (so activate your virtual environment if you deactivated it earlier):

python -m pip install -r requirements.txt

This should start installing all of the modules we've specified in requirements.txt, and from there you can bundle the app with PyInstaller, which was just installed for you.

3 Bundling with PyInstaller (Creating an executable to run)

This is how you can rebundle our application after modifying it.

To bundle the project with PyInstaller, navigate to the root directory /HDRICalibrationTool and open your Python 3.11.1 terminal, and reactivate your virtual environment you created earlier (see 'Create Your Virtual Environment' section above). Run the following command:

PyInstaller --clean --noconfirm --distpath ./ ./HDRICalibrationTool-windows.spec

This should start the bundling process from the pre-built .spec file (PyInstaller bundle config).

At this point, you can run the HDRICalibrationTool-windows.exe in the root directory '~\HDRICalibrationTool' to start the app!

[IMPORTANT] Please keep the .exe file in this directory, else it will not run. If you wish, you can create a shortcut of the .exe and move that to another directory.

3a. Recreating the .spec file

If you need to make changes to the .spec file, you can do so by deleting the old .spec file to be replaced and then building from the command line. A new .spec file will be generated in this process, in addition to the app being bundled.

  • Use the '--add-data "[source];[destination]' flag for the files/directories to bundle.
  • Use the '-n "[Executable Name]"' flag to rename the resulting directory and executable.
  • Use the '--noconsole' flag to hide the terminal window.
    • It's important to not include any space characters in this new name.
  • Warning: using the '--onefile' flag can cause issues regarding source code file path references to resources, so keep the generated executable in the directory it was created in.

For Version 1.0.0, this was the command run to bundle and generate the current .spec file:

pyinstaller main.py -n "HDRICalibrationTool-windows" --add-data "src;src" --add-data "submodules/radiance_pipeline;submodules/radiance_pipeline" --clean --noconfirm --noconsole --onefile --distpath ./

You can ignore the 'build' directory generated upon bundling, as that contains temporary files PyInstaller used when bundling.