This repo contains a template and instructions to help create a new extension for QuPath.
It already contains two minimal extensions, so the first task is to make sure that they work. Then, it's a matter of customizing the code to make it more useful.
There are two extensions to show that you can use either Java or Groovy.
Building the extension with Gradle should be pretty easy - you don't even need to install Gradle separately, because the Gradle Wrapper will take care of that.
Open a command prompt, navigate to where the code lives, and use
gradlew build
The built extension should be found inside build/libs
.
You can drag this onto QuPath to install it.
You'll be prompted to create a user directory if you don't already have one.
The minimal extension here doesn't do much, but it should at least install a new command under the 'Extensions' menu in QuPath.
In case your extension contains external dependencies beyond what QuPath already includes, you can create a single jar file that bundles these along with your extension by using
gradlew shadowJarIf you don't do that, you'll need to drag all the extra dependences onto QuPath to install them as well.
During development, things are likely to be much easier if you work within an IDE.
QuPath itself is developed using IntelliJ, and you can import the extension template there.
However, for development and testing, it can help to import QuPath and the extension and have them in your IDE side-by-side.
In IntelliJ, you can do this in a few steps:
- Get QuPath's source code, as described at https://qupath.readthedocs.io/en/stable/docs/reference/building.html
- Store your extension code in a directory beside QuPath's code. So it should be located next to the
qupath
code directory. - Import QuPath into IntelliJ as a Gradle project (you don't need to import the extension yet!)
- Within
qupath/settings.gradle
add the lineincludeFlat 'your-extension-code-directory'
(updating the code directory as needed) - Refresh the Gradle project in IntelliJ, and your extension code should appear
- Create a Run configuration in IntelliJ to launch QuPath. An example of how that looks is shown below:
Now when you run QuPath from IntelliJ, your extension should (hopefully) be found - there's no need to add it by drag & drop.
There are a few fixed steps to customizing the extension, and then the main creative part where you add your own code.
Open settings.gradle
and check the comment lines flagged with \\TODO
.
These point you towards parts you may well need to change.
Open build.gradle
and follow a similar process to with settings.gradle
, to update the bits flagged with \\TODO
.
For the extension to work, you need to create at least one file that extends qupath.lib.gui.extensions.QuPathExtension
.
There are two examples in the template, in two languages:
- Java:
qupath.ext.template.DemoExtension.java
. - Groovy:
qupath.ext.template.DemoGroovyExtension.java
.
You can pick the one that corresponds to the language you want to use, and delete the other.
Then take your chosen file and rename it, edit it, move it to another package... basically, make it your own.
Please don't neglect this step! If you do, there's a chance of multiple extensions being created with the same class names... and causing confusion later.
For QuPath to find the extension later, the full class name needs to be available in resources/META-INFO/services/qupath.lib.gui.extensions.QuPathExtensions
.
So remember to edit that file to include the class name that you actually used for your extension.
Add a license file to your GitHub repo so that others know what they can and can't do with your extension.
This should be compatible with QuPath's license -- see https://github.com/qupath/qupath
If you follow some conventions in naming your extension and making releases, then other QuPath users will find it easy to automatically install and update your extension!
First, we suggest you name your extension qupath-extension-[something]
, and keep it in its own repository (named the same as the extension),
separate from other projects.
Next, when you want to publish a new version of your extension, use the github_release.yml
workflow included in this repository.
To do so, you'd need to navigate to Actions -> Make draft release -> Run workflow -> Run workflow
as shown in the following screenshot:
This will automatically build the extension, and create a draft release containing the extension jar (and its associated sources and javadoc).
You can then navigate to Releases
and fill out information about the release --- the version, any significant changes, etc.
Once published, users will be able to automatically install the extension as described here:
https://qupath.readthedocs.io/en/0.5/docs/intro/extensions.html#installing-extensions
To enable easy installation and automatic updates in QuPath, fill in the (public) GitHub owner and repository for the extension.
Don't forget to replace the contents of this readme with your own!
For questions about QuPath and/or creating new extensions, please use the forum at https://forum.image.sc/tag/qupath
This is just a template, you're free to use it however you like. You can treat the contents of this repository only as being under the Unlicense (except for the Gradle wrapper, which has its own license included).
If you use it to create a new QuPath extension, I'd strongly encourage you to select a suitable open-source license for the extension.
Note that QuPath itself is available under the GPL, so you do have to abide by those terms: see https://github.com/qupath/qupath for more.