SSEC-JHU flfm_ij_plugin

This is an ImageJ 1.x plugin wrapper for the SSEC FLFM project. This project uses The Deep Java Library(djl) to load the pytorch models exported from the FLFM project.

Quickstart Guide

Get the latest jar file from <release location>. Choose the appropriate release according to your OS. It should be one of:

• flfm_plugin.windows.jar
• flfm_plugin.linux.jar
• flfm_plugin.macos.jar (not currently available)

Place the jar file into the plugins folder for you ImageJ installation.

Open ImageJ and select Plugins from the top menu, then select FLFM Plugin.

Tip

ISSUES DETECTING GPU? Sometimes there can be an issue with the detection of the GPU when running the plugin. There a couple things that you can do to fix this issue:

1. Start ImageJ with the plugin jar on the classpath:

• Open a terminal in the directory of the ImageJ installation
• Linux:
  • ./ImageJ -cp plugins/flfm_plugin.linux.jar
• Windows:
  • ImageJ.exe -cp plugins\flfm_plugin.windows.jar

2. Add the DJL cache to the PATH variable. The DJL library will download\extract the required libraries to run the FLFM pytorch code to the DJL cache location. This can be set manually by following the DJL documentation The default location is something like:

• Linux:
  • ~/.djl.ai/pytorch/2.5.2-cu124-linux-x86_64/
• Windows:
  • C:\Users\<username>\.djl.ai\pytorch\2.5.1-cu124-win-x86_64\

Installation, Build, & Run instructions

Build:

To build the project requires two steps:

1. Use the FLFM python package to export model files for all desired iterations (current [1-15]).
2. Build the Java plugin using Maven with the model files copied into the src/main/resources/models directory.

For convenience, the make file will do all of this for you, but you need to have the following prerequisites installed:

• conda

• maven

  Docker:

  (TODO)

  Locally:

  1. Clone the repository:

     git clone https://github.com/ssec-jhu/flfm-ij-plugin.git

  2. Change into the repository directory:

      cd flfm-ij-plugin

  3. Run the make command:

     make linux

     or

     make windows

If you need to rebuild the project it is recommended to clean the project first:

make clean

Run

This plugin can be run as a standalone jar and as an ImageJ 1.x plugin with the latter being the general use case and the former being more helpful for debugging and testing, but functional nonetheless.

ImageJ 1.x Plugin

To run this in ImageJ 1.x, copy the .jar for your OS flfm_plugin.<linux|windows>.jar into the plugins folder in your ImageJ installation, then start ImageJ.

Standalone

Using Java 8, the jar can be run directly using:

java -jar flfm_plugin.<linux|windows>.jar

Where <linux|window> should be replaced with the OS you're running it on.

Usage:

The standalone jar opens directly to the FLFM PLugin UI, if it's being run as an ImageJ plugin there is a single step to get to the plugin.

Open ImageJ and from the Plugins menu select FLFM Plugin:

This will open the FLFM Plugin Menu:

To use the plugin populate the fields with the desired values and click Calculate

NOTE on image selection

When you try to select an image, the Plugin will first try to get an image already opened in ImageJ with the following menu popping up:

If the plugin doesn't detect any open ImageJ images or if you close the menu, the plugin will open a file selector menu to select an image from disk.

Testing

Linting:

Facilitates in testing typos, syntax, style, and other simple code analysis tests.

• cd into repo dir.

• Use Spotless to check code formatting:

  mvn spotless:check --file flfm-ij/pom.xml

• Use Checkstyle for linting the code:

  mvn checkstyle:check --file flfm-ij/pom.xml

Security Checks:

Facilitates in checking for security concerns using SpotBugs.

• cd into repo dir.
• mvn -B spotbugs:check --file flfm-ij/pom.xml

Unit Tests:

Facilitates in testing core package functionality at a modular level.

• cd into repo dir.

• Run all available tests:

  mvn clean test --file flfm-ij/pom.xml

Regression tests:

Facilitates in testing whether core data results differ during development.

• WIP

Smoke Tests:

Facilitates in testing at the application and infrastructure level.

• WIP

Build Docs:

Facilitates in building, testing & viewing the docs.

• cd into repo dir.
• pip install -r requirements/docs.txt
• cd docs
• make clean
• make html
• To view the docs in your default browser run open docs/_build/html/index.html.