Paths and configuration

This section contains some potentially useful information about important paths and settings when launching QuPath - and how they can be modified to do more interesting things.

Here are some places where pieces of the picture are described:

Working-with-MATLAB
Working-with-Python
This post about setting up QuPath with Python (via JEP)

The general idea

For all Java applications, two sets of paths are very important:

The Java classpath - which specifies exactly which Java files (generally .jar files) are available to QuPath when it is running
The Java library path - which specifies the directories in which Java will search for native libraries

If a .jar isn't on the classpath, QuPath won't find it - even if it's in the same directory as other Jars that QuPath does know about.

On the other hand, if a native library is in the same directory as native libraries that QuPath already uses then it's most likely that QuPath will be able to find it.

The Java classpath

When QuPath is launched 'normally' all the Jars on the classpath are set inside a file named QuPath.cfg.

Therefore new Jars can be added simply by appending the Jars to this list.

However, QuPath is also set up to be able to automatically find Jars found within a specific directory: the QuPath extensions directory. This can be specified inside the Preferences, or alternatively a prompt will appear asking to choose an extensions directory if a Jar is dragged onto QuPath while it is running.

The extensions directory provides a way to add Jars to the classpath without needing to modify the QuPath.cfg file.

The Java library path

The Java library path can be more troublesome than the classpath. It isn't needed to incorporate any extra code written entirely in Java (for which the classpath is used), but is essential to access native libraries (e.g. those written in C/C++) such as OpenCV or OpenSlide.

Native libraries have extensions dependent on the platform, e.g. .dll, .jnilib, .dylib or .so.

The library path can't be set dynamically from within a running Java application (well, not without some slightly dubious trickery), but rather needs to be specified before the application is started.

By default, QuPath will look for native libraries in the directory containing QuPathApp.jar - this is where the OpenSlide and OpenCV libraries are bundled with QuPath.

It is possible to add new native libraries simply by copying them to this directory. Alternatively, an alternative library path can be specified within the QuPath.cfg file.

For example, Working-with-MATLAB shows how this can be done to add the MATLAB native libraries running on a Mac:

[JVMOptions]
-Djava.library.path=/Applications/MATLAB_R2016b.app/bin/maci64:.:../MacOS

The situation should be similar, albeit with different directories, for other applications.

Individual directories that should be included on the path can be separated by : on Mac or Linux, or (probably) ; on Windows.

An important thing to note is that, if the native libraries that QuPath uses by default should remain accessible, any modifications to QuPath.cfg also need to include the directories that QuPath normally uses. For this reason, . is added above, to ensure that the 'current directory' (i.e. the one containing QuPathApp.jar) will be included.

In the above example, ../MacOS is added as well. This is because the ability to set the maximum memory within QuPath requires access to a native library called packager - which is not included in the same directory as the others by default.

Therefore it is a good idea to ensure that the directory containing this packager library is also included in any modified version of the Java library path.