WEBKNOSSOS

/

TUTORIAL

Multi-tile alignment in WEBKNOSSOS

·

Nov 2026

Large sections are often imaged as several overlapping tiles. Before you can explore or annotate the volume, the tiles of each section need to be stitched together, and the sections need to be aligned to each other. With alignment projects, now in beta, WEBKNOSSOS does both. You upload your tiles once, start one or more alignments, and each alignment creates a new dataset. In this tutorial, we walk through the whole workflow with an example dataset.

Watch the full video on YouTube.

Prepare your data

An alignment project needs two things: the tile images and one CSV file that says where each tile belongs. Put them in a folder, for example with one subfolder per section as in our data. You can upload that folder directly, or as a ZIP archive.


Finder window showing one folder per section and the six tiles of section_050

One folder per section, with its tile images

The tile CSV lists one tile per row, with four columns: the section index, the tile's x and y position within its section in pixels, and the path of the image file.

50,6,2,./section_050/tile_0_0.tif
50,429,0,./section_050/tile_1_0.tif
50,871,5,./section_050/tile_2_0.tif
50,0,395,./section_050/tile_0_1.tif
50,426,405,./section_050/tile_1_1.tif
50,889,392,./section_050/tile_2_1.tif
51,6,0,./section_051/tile_0_0.tif
50,6,2,./section_050/tile_0_0.tif
50,429,0,./section_050/tile_1_0.tif
50,871,5,./section_050/tile_2_0.tif
50,0,395,./section_050/tile_0_1.tif
50,426,405,./section_050/tile_1_1.tif
50,889,392,./section_050/tile_2_1.tif
51,6,0,./section_051/tile_0_0.tif

A few things to keep in mind:

  • The x and y values are initial positions, for example from the microscope stage. They don't need to be exact: finding the exact positions is what the alignment does.

  • Neighboring tiles should overlap a little, so their shared structures can be matched.

  • Section indices must be contiguous, but they can start at any value. Our sections run from 50 to 67.

  • Paths are relative to the CSV and must stay inside its folder.

The full format is described in the documentation.

Create an alignment project

In the navbar, open Analysis, then Alignment Projects, and click New Alignment Project. Creating projects is available to admins and dataset managers.


Opening Analysis, then Alignment Projects, and clicking New Alignment Project

Creating a new alignment project

Upload the tiles and the CSV

Drop your folder or ZIP archive into the upload area. The project name is taken from the file name, and you can change it. Enter the voxel size of your data and its unit, then click Upload.


Dropping the ZIP archive, entering the voxel size and uploading

Dropping the ZIP archive, entering the voxel size and uploading

You only upload the data once. From then on, you can start as many alignments from it as you need, for example with different settings.

Check the project page

After the upload, the project page shows the project details, such as the number of files, the sections and the voxel size, and the list of its alignments.


Project page with the tile CSV and its Replace button highlighted

The project page, with the tile CSV and its Replace button

WEBKNOSSOS checks the tile CSV after the upload. If something is wrong, the project page states the reason. You can then replace the CSV with Replace, without uploading the tiles again. This is also how you correct initial tile positions, or leave out a bad tile: remove its row and replace the CSV. Alignments that are running or already finished keep the CSV they were started with.

Start an alignment

Click Start Alignment. In the dialog, you choose:

  • Sections: all sections, or a subset.

  • Output: Align stitches the tiles, aligns the sections and writes the aligned data.

  • Output dataset name and target folder for the new dataset.

Then click Start alignment. Alignments are free during the beta.


Start Alignment dialog: picking the target folder and starting the alignment

Picking a target folder and starting the alignment

Follow the job and open the result

The alignment runs as a background job. You can follow its progress on the Processing Jobs page, under Analysis, and WEBKNOSSOS notifies you by email once it has finished. When the job succeeds, click View to open the new dataset.


Processing Jobs page: clicking View on the finished alignment job

Opening the aligned dataset from the Processing Jobs page

The tiles of each section are now stitched, and the sections are aligned from one slice to the next.


Scrolling through the sections of the aligned dataset

Scrolling through the aligned sections

Larger projects

Alignment projects are still in beta, and the tile CSV is the only supported input format for now. For larger projects, contact us or have a look at our alignment services.

We hope this tutorial helps you get started with your own tiled data. Try alignment projects on webknossos.org, and let us know how it works for you.

. . .

Data: Luke Noon, CIPF-ISABIAL, 3D-EM Unit (Valencia, Spain).

WEBKNOSSOS

Annotate, proofread, and analyze large 3D microscopy datasets in the browser.

WEBKNOSSOS

Annotate, proofread, and analyze large 3D microscopy datasets in the browser.