This extension for QuPath imports annotations made on .svs
files using
PaperJS in combination with OpenSeaDragon.
This extension is currently only compatible with QuPath 0.1.2
The coordinates, color, and other metadata of the annotations must be saved in a .json
file, structured as follows:
{
"SourceSlide": "name-of-file.svs",
"dictionaries": [
{
"uid": "some-uid",
"name": "some-name",
// http://paperjs.org/reference/path/
"path": {
"data": {
"id": "some-uid"
},
"segments": [
// http://paperjs.org/reference/segment/#segment
[
[0.0, 0.0],
[0.0, 0.0],
[0.0, 0.0]
],
// ...
],
"closed": true,
"fillColor": [0.0, 0.0, 0.0, 0.0],
"strokeColor": [0.0, 0.0, 0.0],
"strokeWidth": 50,
}
"label": "Tumor" // (See `qupath.lib.objects.PathClass`)
}
]
}
A working example can be found below:
Full Example
{
"SourceSlide": "24496.svs",
"dictionaries": [
[
{
"uid": "dc466dd0-15f7-11ea-94f7-3541d0425afc",
"name": "dc466dd0-15f7-11ea-94f7-3541d0425afc",
// http://paperjs.org/reference/path/
"path": {
"applyMatrix": true,
"data": {
"id": "dc466dd0-15f7-11ea-94f7-3541d0425afc"
},
"segments": [
// http://paperjs.org/reference/segment/#segment
[
[4445.56952, 2904.39074],
[0.9558, 6.05342],
[-0.28748, -1.82071]
],
[
[4444.66043, 2909.84528],
[1.02246, -1.53369],
[-2.18812, 3.28217]
],
[
[4445.56952, 2921.66346],
[-4.38693, -2.19347],
[0.19696, 0.09848]
],
[
[4448.29679, 2922.57255],
[0.00906, 0.09063],
[-0.6098, -6.09799]
]
],
"closed": true,
"fillColor": [0.81569, 0.41569, 0.41569, 0.5],
"strokeColor": [0.81569, 0.41569, 0.41569],
"strokeWidth": 50
},
"label": "Tumor"
}
]
]
}
In the future, there will be efforts to remove redundant entries, and to improve the overall data structure (i.e. transform arrays to hash-tables where it makes sense, and vice versa)
The following installations are required to build the
AnnotationExchangeExtension.jar
artifact:
-
Java Development Kit
8u151
(JDK 1.8.0_151
) (Requires registering for an Oracle account)
A build of QuPath (v0.1.2) is
required to ensure the Java compiler does not complain about the classes
AnnotationExchangeExtension
extends.
Previous developers have built an artifact of QuPath.jar
, and set that as a
dependency of AnnotationExchangeExtension
. However, you may be able to set the
QuPath
project as a dependency of AnnotationExchangeExtension
without making
a build of it. If you are successful in doing the latter, you can skip this
step.
- Clone QuPath
git clone [email protected]:qupath/qupath.git
# If you do not have an SSH key from your current terminal associated with your
# GitHub account, use the https link here:
git clone https://github.com/qupath/qupath.git
# The extension currently only works for the 0.1.2 release of QuPath
# It is crucial you do this before loading the project into IntelliJ, as later
# releases of QuPath use `Gradle` as the dependency manager, whereas earlier
# releases use `Maven`, which may confuse IntelliJ regarding which dependency
# manager to use
git checkout v0.1.2
- Load the project into IntelliJ
- File -> New -> Project From Existing Sources
- Choose the
qupath/
directory you just cloned - Click the Radio button for
Import project from external model
- Choose
Maven
- Leave all the defaults, and keep clicking
Next
untilFinish
- Change the compiler settings
-
File -> Settings... -> Build, Execution, Deployment -> Compiler -> Java Compiler
-
Set
Project bytecode version
to1.8
-
For all rows in the
Per-module bytecode version
table, ensure each one hasTarget bytecode version
set to1.8
-
Then go to Build, Execution, Deployment -> Compiler -> Annotation Processors, and ensure that
Enable annotation processing
is not checked off for the modules under theDefault
dropdown, as well as theMaven default annotation processors profile
-
File -> Project Structure... -> Modules
For each module listed, click the
Sources
tab, and ensure eachLanguage level
dropdown option is set to8 - Lambdas, type annotations etc.
- Add module dependencies
- File -> Project Structure... -> Modules -> Click the
qupath
module
Click the Dependencies
tab, and add Module Dependencies:
Add all qupath-*
modules, and check them off:
- Build QuPath
.class
files
- You should now be able to build the project by going to Build -> Build Project
(or
Ctrl+F9
), and if there are no issues, you should see the following on the bottom left of theIntelliJ
window:
This means you should now be able to make QuPath.jar
- Set up making
QuPath.jar
- File -> Project Structure... -> Artifacts
Leave Module
as <All Modules>
.
For Main Class
, browse your file system with the ...
button, click the
Project
tab, and select src/main/java/qupath/QuPath.java
Your Artifacts
screen should look like:
Note how all the maven
dependencies (.m2/repository
) are included in the
build, which AnnotationExchangeExtension
will rely on.
Build the artifact by going to Build -> Build Artifacts... -> qupath
-> Build
And the resulting file will be at:
/path/to/qupath/out/artifacts/qupath/qupath.jar
We now have the dependencies needed to build AnnotationExchangeExtension
- Clone
qupath-annotation
[email protected]:bcgsc/qupath-annotation-exchange.git
# If you do not have an SSH key from your current terminal associated with your
# GitHub account, use the https link here:
https://github.com/bcgsc/qupath-annotation-exchange.git
- Load project into IntelliJ
- File -> New -> Project From Existing Sources
- Choose the
qupath-annotation-exchange/
directory you just cloned - Click the Radio button for
Import project from external model
- Choose
Gradle
- Leave all defaults and click
Next
until theFinish
button - Replace the
.idea/
directory if it prompts you to do so
- Set
Qupath.jar
as a dependency
- File -> Project Structure... -> Libraries -> + -> Java
Find the directory where qupath.jar
was created:
Add qupath
to all AnnotationExchangeExtension
modules:
- File -> Project Structure... -> Modules
For each of the module options, highlighted with <-
:
AnnotationExchangeExtension
AnnotationExchangeExtension_main <-
AnnotationExchangeExtension_test <-
AnnotationExchangeExtension <-
Ensure that the qupath
library is checked:
- Make a build of
AnnotationExchangeExtension
If the build was successful, you should see this at the bottom left of the
IntelliJ
window:
- Set up creating an
AnnotationExchangeExtension
artifact
- File -> Project Structure... -> Artifacts -> + -> JAR -> Empty
-
Set the
Name:
toAnnotationExchangeExtension
-
Choose the module
AnnotationExchangeExtension_main
+
-> Directory Content
- Choose
/path/to/qupath-annotation-exchange/src/main/resources
- Build
AnnotationExchangeExtension.jar
Build -> Build Artifacts... -> AnnotationExchangeExtension -> Build
- Import
AnnotationExchangeExtension.jar
inQuPath
Use your file system explorer to navigate to
/path/to/qupath-annotation-exchange/out/artifacts/AnnotationExchangeExtension
Open an installed version of QuPath
:
And drag the built AnnotationExchangeExtension.jar
file into the QuPath
window. If QuPath prompts you to, accept a restart.
Click the Extensions button, and if you see "Annotations Exchange", with
options "Import JSON Annotation" and "Export JSON Annotation", congratulations,
you have successfully made a build of AnnotationExchangeExtension
and added
it to QuPath
.
If you have an .svs
file, and annotations made using an application that
conforms to the JSON structure (i.e. the internal GSC React application), you
can now overlay those annotations over the .svs
file: