Project structure

This section is intended primarily for the particularly enthusiastic, who want to know more about how projects are structured - and possibly to hack them a bit to improve behavior or fix an error. It may also be helpful for someone who has accidentally messed around with their project directory, or found that it has somehow become corrupt, and wants to fix it again.

The information in this section may change. It is planned to make projects more sophisticated in the future.

Contents of a QuPath project

QuPath projects start off as empty directories (folders), into which QuPath adds several files and subdirectories in an organized way. A typical project should contain the following.

The project file (.qpproj) (essential)

The main project file is a simple text file (more accurately, JSON) that contains the full paths to all the images in the project. These files can be opened and edited in any text editor if necessary.

If you create a project with a lot of images in it, and then move the images later to another directory, their paths will be wrong inside the .qpproj file. In this case, you may be able to recover the situation elegantly by opening the .qpproj file and running a carefully-chosen Find & Replace operation to update the paths. Then you can reopen the project in QuPath, and hopefully all will be well again.

The data subdirectory (essential)

This contains the .qpdata files for the project - one for each image. The name of the .qpdata file is determined by the 'short' file name name of the image it corresponds to, i.e. the file path with the parent directory part chopped off.

Warning! If a project contains two images with the same short name (but inside different folders, therefore having different paths), QuPath does not currently handle this in any smart way... it will instead confuse itself by having one qpdata file that relates to two images. So please try to avoid this!

The thumbnails subdirectory (optional)

This contains a small version of each image, used to display as a preview within QuPath. Deleting this directory shouldn't cause any trouble - QuPath will recreate it when it needs to.

The scripts subdirectory (optional)

This directory can be used to store any scripts relating to the analysis for this project. These scripts will appear in the Automate → Project scripts... submenu within QuPath for easy access.

It isn't essential to store your scripts in this subdirectory, but it's a good way to keep things organized.

The classifiers subdirectory (optional)

Similar to the case with scripts, this directory provides a way to keep your detection classifiers organized alongside the project they relate to.

Other files & subdirectories

It's quite possible that QuPath will start to use other files and subdirectories within its projects in the future. So it is best not to put your own stuff inside your project directories, unless you are very confident that your naming scheme is sufficiently idiosyncratic that it won't cause any conflicts at a later date.

Examples of the kind of names you should avoid are things like export, results and workflows... since subdirectories with these names are quite likely to be added to QuPath one day.