How do I create a project?

How do I create a project?#

What will I learn?

  • How to create a project

  • How to add images

  • How to remove images

  • How to mask file names

  • How to fix a project when the images are moved

QuPath uses projects to manage multiple images and the data generated as you analyse.

A project is basically a folder on your computer. It contains the paths to the images – not the image files themselves. This helps keeps projects small and means that the original image doesn’t need to be copied.

When working with QuPath, you should almost always be using a project to keep everything organised.

The only exception is if you want to just quickly look at an image: then you can simply follow the instructions in How do I open an image. But if you’re working with multiple images, or saving data, you should do this in a project.

How to create a project#

What to do

  1. Create an empty folder on your computer (e.g. in Windows Explorer or Mac Finder).

  2. Drag the folder onto the main QuPath window.

Drag & drop isn’t the only option - you can also press the Create project button or select File ‣ Project ‣ Create project…, then choose the folder you created. But drag & drop is usually faster.

You should then see something like this (notice the folder name on the left pane is demo_project):

../../_images/project_created.png

Fig. 15 An empty QuPath project#

How to add images#

What to do

  1. Drag CMU-1.svs, CMU-1-Small-Region.svs and OS-2.ndpi onto QuPath.

Drag & drop also works for adding images to a project. You can add multiple files at the same time. If QuPath recognizes them as images, you will see the import images to project window

../../_images/import_images.png

Fig. 16 Importing images into a project#

A few options can be set at the bottom of the window. The most important are:

  • Image server: this is the library used to read the image. QuPath will always try to find the most suitable library, but you can override this setting here. Keep Default here (it should select OpenSlide).

  • Image type: the image type is used by QuPath for stain separation by some commands, for example the cell detection. If all the images are the same type, you can specify it here and then you won’t see the prompt to choose the type when opening the image later.

Because the two images we’re importing have different types, we won’t specify the type here.

What to do

  1. Click on Import.

You should now see the images listed in the Project tab and be able to open them by double-clicking on them.

../../_images/images_imported.png

Fig. 17 Images imported into a project#

How to remove images#

What to do

  1. Check that CMU-1-Small-Region.svs isn’t already open in QuPath’s viewer.

    • If it is, double-click a different image to open it instead.

  2. In the Project pane, right-click on CMU-1-Small-Region.svs and choose Remove image.

  3. Agree to any prompts that appear to remove the image from the project.

If you added any images to a project that you no longer need, the easiest way to get right of them is by right-clicking on the unwanted images under the Project pane to review the Remove image option.

This also works if you select multiple images.

How to hide file names#

What to do

  1. Right-click inside the Project pane and choose Mask image names.

    • You should see the images are shuffled and the names are replaced by random text.

  2. Right-click on an image in the Project tab and choose Mask image names again.

    • You should see the names are restored to normal.

File names in science can be magnificent monuments to understanding, packed full of information about experimental conditions in concise way (which is comprehensible at least to the person who named the file originally, if no one else).

However, that’s not always a good thing. Sometimes, you need to do some analysis without knowing which images or conditions you are seeing – since that could bias the interpretation.

That’s where Mask image names is useful. This can replace the image name with an incomprehensible collection of characters, but in a way that is easily revertible.

It will also shuffle the order of the images, in case you happened to remember conditions from that.

Troubleshooting: If your images have moved#

What to do

  1. Download My broken project.zip from OneDrive

  2. Unzip the zip file to get the My broken project folder

    • On Windows you’ll need to right-click and extract the contents

    • On Mac you only need to double-click the zip file

  3. Try to open the project by dragging the folder onto QuPath or using File ‣ Project ‣ Open project….

Since QuPath stores the path to each image in relation to the project, the project won’t work if the path changes (e.g., your images move) or a project is transferred across computers.

QuPath detects that, and pops up a dialog to help you reunite the images with their project.

../../_images/URIproblem.png

Fig. 18 Missing image file requesting a new URI#

What to do

  1. Select Search and locate the folder containing the missing images.

  2. Select OK to update the URI.

As long as the filenames for the specific images haven’t changed, and the names are unique, QuPath should be able to match them up again – and the project will still work.

Tip

If just the one image goes missing (possibly due to being renamed), instead of selecting Search in the dialog, you can double-click the red URI of the missing image individually.

URI stands for Uniform Resource Identifier, which in this case is just a fancy way of representing the “file path”.

Tip

Images can be stored within the project folder itself. This means that if you move the folder, the images URIs will still be correct and the images found. This can be useful when sharing projects with others, though it can make the project folder quite large.

See also

Contents