Windows Installation Guide and Troubleshooting - radiantlab/HDRICalibrationTool GitHub Wiki

Installation

This page will guide you to run our application starting from downloading the repository. It is intended for users who wish to simply download and run the app.

For information on editing the source code and re-bundling the app, see the "Environment Setup" page in the "Making Changes" section in the sidebar.


[IMPORTANT] Prerequisites for use

As of v1.0.0, Windows users must have:

  • Windows 10 OS version
    • This app has not been tested on earlier versions of Windows.
    • This app has been attempted to be used on Windows 11, with poor results due to compatibility. It is highly not recommended to use this application on Windows 11, as the behavior is unexpected and performance is poor.
  • sed for windows must be installed and on PATH
  • Radiance must be installed and on the PATH
  • HDRgen must be installed and on the PATH
  • Git must be installed so you can clone, edit, then push changes to our source code repository, as well as retrieve the necessary radiance_pipeline submodule files if you download this repository using the method in Section 1b.
  • When merging raw images (.cr2 files), extra software needs to be installed. In this case, please read the Wiki page "Raw Image Files" in the "Step by Step Guide" section.

1. Downloading the source code from the repository

1a. Latest release

You can download the latest release of the project by clicking on the latest release in the "Releases" section on the repository "Code" tab:

windows_download_1

Next, scroll down to the "Assets" section, and click to download the HDRICalibrationTool_USE_ME.zip file to the desired location on your computer. You can then unzip this.

  • Note: The reason that the release is in this .zip and not the 'Source code .zip' is that the radiance_pipeline Git submodule that our app relies on to actually process the user input can only be added to a git release as an additional binary upload, rather than replaceing the auto-generated 'Source code .zip'.

1b. Code tab .zip

Alternatively, on the "Code" tab of the repository, click the green "Code" dropdown button and choose the "Download Zip" option. Once it downloads, you can unzip it to your desired location

  • Note:
    • This will NOT include the radiance_pipeline submodule files when downloaded this way (See Section on updating the submodule below).
    • This does NOT guarantee that the .zip is the latest release-- it may include files that have changes in review. For the most stable version of the app, it is recommended to download via the Latest Release (See Section 1a).

image

Updating the radiance_pipeline submodule

If your '~\HDRICalibrationTool\submodules\radiance_pipeline' directory is empty, either by downloading via the Code tab in Section 1b, or you downloaded the incorrect .zip file in the Release section, you can grab the most recent version with Git.

  1. Open a Git terminal in the '~\HDRICalibrationTool' root directory.
  2. Run the following command: git submodule --init --remote --recursive

Your \radiance_pipeline directory should now be populated with files.


2. Launching the application

Once your code is downloaded and unzipped, you should have the directory '~\HDRICalibrationTool', where the '~' means whatever parent directory you have on your machine. This is the root directory of our app.

Inside the app's root directory, you will find an executable called 'HDRICalibrationTool-windows.exe', which you can double-click to run, and the app will launch!

image

[IMPORTANT] Please do not move the 'HDRICalibrationTool-windows.exe' file from the root directory, nor any of the source files in the following directories:

  • '~\HDRICalibrationTool\main.py'
  • '~\HDRICalibrationTool\src'
  • '~\HDRICalibrationTool\submodules'

If you wish to relocate the .exe file to a more convenient location, you can create a shortcut and move the shortcut.


Windows-specific troubleshooting

Here are some issues and potential solutions we came up with while developing the application.

Radiance/HDRGen/Python/sed not found

Ensure these apps are all on your PATH (see: https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14))

My apps are on my PATH and still getting an error

Restart your machine after adding to PATH.

Application and console window closes with no error message

You can check the 'temp' directory located at ~\HDRICalibrationTool\dist\HDRICalibrationTool\temp and look at the file sizes. If any are 0 Bytes, the step that creates that output has an issue.

output9.hdr and output10.hdr both have a size of 0KB

A common cause for this is that 'sed for windows' is not installed, or it's not on the system PATH. It's worth noting that after adding it to the PATH, restarting the computer may be necessary for it to be found on PATH.

Ensure 'sed for windows' is on the system PATH. The default install location is something like 'C:\Program Files (x86)\GnuWin32', and I added the directory 'C:\Program Files (x86)\GnuWin32\bin' to my PATH so that 'sed.exe' inside of the \bin folder could be found

After using PyInstaller to rebundle the app after changes, the terminal closes and the app won't open

You can open command prompt or powershell in the directory of the .exe file, and run it from command prompt. The error the app outputs before instantly closing will now print to the terminal window and you can read the error.