ThermImageJ - Thermal Image Functions and Macros for ImageJ

<img src = './images/ThermImageJSticker1.png' align="right" height="165">

ThermImageJ is a collection of ImageJ functions and macros to allow for import and conversion of thermal image files and to assist in extracting raw data from infrared thermal images and converting these to temperatures using standard equations in thermography.

These macros will allow you to import most FLIR jpgs and videos and process the images in ImageJ.

ThermImageJ emerged from Thermimage (https://github.com/gtatters/Thermimage), the latter an R package with similar tools but more emphasis on biological heat transfer analysis.

Compatibility

• ThermImageJ was developed on OSX, and tested using ImageJ v1.52o. Many features require installation of command line tools that may present future challenges on different operating systems. Testing and troubleshooting is ongoing, especially in Windows. Please report issues here: https://github.com/gtatters/ThermImageJ/issues, or consider converting to Mac or Linux.

How to Cite

• Glenn J. Tattersall. (2019). ThermImageJ: Thermal Image Functions and Macros for ImageJ. doi:10.5281/zenodo.2652896.

Requirements

External Software Downloads

• FIJI is Just ImageJ. Download instructions: https://imagej.net/Fiji/Downloads
• Exiftool. (The standalone executable file is suggested).
  • Installation instructions: http://www.sno.phy.queensu.ca/~phil/exiftool/install.html
  • Windows users might find these instructions do not work readily, so perhaps try this link: https://oliverbetz.de/pages/Artikel/ExifTool-for-Windows - but this has not be fully tested with ThermimageJ
  • I prefer the simple solution of installing exiftool.exe directly into the windows folder and then verifying it has security privileges to run.
• FFMPEG command line utility (static version).
  • Download instructions: https://ffmpeg.org/download.html
  • Choose the “get packages and executable files” to facilitate an easy installation unless you prefer to work with the source code
  • Choose the static build.
• Perl. (Activeperl binary is suggested, although perl may already be built into your operating system).
  • Installation instructions: https://www.perl.org/get.html
• Byte swapper plugin.
  • Download instructions: https://imagej.nih.gov/ij/plugins/swapper.html
• xxd (command line utility should already be part of OSX and Unix systems)
  • A windows version can be downloaded from: https://sourceforge.net/projects/xxd-for-windows/ or sourced from the exe folder provided at: https://github.com/gtatters/ThermimageJ/exe

ThermImageJ Downloads from this Github site

• All ThermImageJ files can be easily downloaded as a ZIP file by clicking on the green Clone or Download button and then selecting Download ZIP (https://github.com/gtatters/ThermImageJ/archive/master.zip), or by going to the Recent Releases (https://github.com/gtatters/ThermImageJ/releases) and selecting the Source Code link for the most recent release. Unzip this folder on your computer for access to the toolset, luts, and the split.pl files located in their appropriate subfolders.

• The primary files you need to extract from this site are:

  • A custom perl script (split.pl), provided on this github repository, which can be downloaded and placed in a scripts folder with ImageJ: https://github.com/gtatters/ThermImageJ/tree/master/scripts/split.pl

  • ThermImageJ macro toolset. A text file (.ijm) containing all the macros and functions: https://github.com/gtatters/ThermImageJ/tree/master/toolsets/ThermImageJ.ijm

  • Additional Look Up Tables (LUTS), popularly used in thermal imaging, available on this github repository: https://github.com/gtatters/ThermImageJ/tree/master/luts

Installation Instructions

• Install FIJI, exiftool, perl, and ffmpeg according to the website instructions above.
• Troubleshoot or perform installation checks (see next section).
• Launch FIJI and follow any update instructions.
• Launch FIJI–>Help–>Update, allow it to update any plug-ins, then while the update window is open, select Manage update websites, and ensure that the FFMPEG box is ticked. Select ok, then click the Apply option, and restart FIJI. This FFMPEG plugin is required for importing avi files created during the conversion process, although it might require that you have FFMPEG installed at the command line.
• Navigate to where FIJI is installed to find all the subfolders.
• Download the ThermImageJ.ijm file from this site and copy into the FIJI/macros/toolsets folder.
• Open the ThermImageJ.ijm file in any text editor, and verify the paths are properly set for your respective operating system. See the comments with the text file for guidance. Most of the default locations are likely fine, although FFMPEG is sometimes installed in different folders depending on what the user might have selected.
• Download the additional luts files from this site and copy into your FIJI/luts folder. These are palettes that are commonly used in thermal imaging.
• Download the perl script, split.pl from this site and copy into a FIJI/scripts folder.
• Download Byte_Swapper.class to the plugins folder.
• Restart ImageJ.
• If everything succeeded (see checks below), the toolset should be installed and visible from your plugins menu.

Installation Checks

Verify exiftool is installed by launching a terminal (or cmd prompt) window and typing the following bash commands:

exiftool -ver
which exiftool

## 12.62
## /usr/local/bin/exiftool

If you see a version number (probably > 10) and no error, then exiftool is installed properly. The second line will tell you the path to where it is installed.

Do the same for perl:

perl -ver
which perl

## 
## This is perl 5, version 38, subversion 0 (v5.38.0) built for darwin-thread-multi-2level
## 
## Copyright 1987-2023, Larry Wall
## 
## Perl may be copied only under the terms of either the Artistic License or the
## GNU General Public License, which may be found in the Perl 5 source kit.
## 
## Complete documentation for Perl, including FAQ lists, should be found on
## this system using "man perl" or "perldoc perl".  If you have access to the
## Internet, point your browser at https://www.perl.org/, the Perl Home Page.
## 
## /usr/local/bin/perl

Verify no errors on your system to ensure perl is installed correctly.

Check that the perl script is accessible by perl (be sure to provide the proper path to the split.pl file on your system):

perl /Applications/Fiji.app/scripts/split.pl

You should see the following warning message:

“Error: Please specify input file, output folder, the output filename base, pattern to split, and output file extension.”

This is a good error, and verifies that the perl script is installed where your machine can access it!

If you see:

“Can’t open perl script”/Applications/Fiji.app/scripts/split.pl”: No such file or directory”

you will need to re-check the location of the script or the path information provided at the top of the ThermImageJ.ijm file.

Now, do the same for ffmpeg:

ffmpeg -version
which ffmpeg

## ffmpeg version 6.1.1 Copyright (c) 2000-2023 the FFmpeg developers
## built with Apple clang version 15.0.0 (clang-1500.1.0.2.5)
## configuration: --prefix=/usr/local/Cellar/ffmpeg/6.1.1_2 --enable-shared --enable-pthreads --enable-version3 --cc=clang --host-cflags= --host-ldflags='-Wl,-ld_classic' --enable-ffplay --enable-gnutls --enable-gpl --enable-libaom --enable-libaribb24 --enable-libbluray --enable-libdav1d --enable-libharfbuzz --enable-libjxl --enable-libmp3lame --enable-libopus --enable-librav1e --enable-librist --enable-librubberband --enable-libsnappy --enable-libsrt --enable-libssh --enable-libsvtav1 --enable-libtesseract --enable-libtheora --enable-libvidstab --enable-libvmaf --enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxml2 --enable-libxvid --enable-lzma --enable-libfontconfig --enable-libfreetype --enable-frei0r --enable-libass --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libopenvino --enable-libspeex --enable-libsoxr --enable-libzmq --enable-libzimg --disable-libjack --disable-indev=jack --enable-videotoolbox --enable-audiotoolbox
## libavutil      58. 29.100 / 58. 29.100
## libavcodec     60. 31.102 / 60. 31.102
## libavformat    60. 16.100 / 60. 16.100
## libavdevice    60.  3.100 / 60.  3.100
## libavfilter     9. 12.100 /  9. 12.100
## libswscale      7.  5.100 /  7.  5.100
## libswresample   4. 12.100 /  4. 12.100
## libpostproc    57.  3.100 / 57.  3.100
## /usr/local/bin/ffmpeg

Setting and verifying paths to command line tools

Once you have installed everything above, and verified no errors, you can check or change the directory paths in FIJI/ImageJ.

The ThermImageJ.ijm toolset file will detect whether you are using Mac OSX, Linux or Windows and attempts to define the appropriate file paths automatically. Thus, you should not need to change parameters, but it is useful to check and become familiar with the process or do any customisation necessary for your FIJI installation.

Navigate to the ThermImageJ.ijm toolset file and open it using a text editor or the built-in ImageJ macro editor:

<img src="./images/ToolsetHeader.png" width="100%" />

Depending on your operating system or how system files are installed you may need to edit the specific path locations for your respective system:

<img src="./imag