LocaliZoom

LocaliZoom is a pan-and-zoom type viewer displaying high-resolution image series coupled with overlaid atlas delineations. Both linear (QuickNII) and nonlinear (VisuAlign) registrations are supported. User documentation is provided on readthedocs.io, source code is on GitHub.

Three operating modes

The catch

Accessing LocaliZoom

It's important to point out that the most painless way for researchers is to register an EBRAINS account (free of charge but requires either an email address from a research institution, or a plausible use case), then image conversion is covered too.

And the other way is hosting a custom data source and using LocaliZoom with that one. In this case image conversation may be a pain, but no registration is needed.

Configuration

LocaliZoom is configured via its configuration.js file (general settings for the deployment) and some URL parameters (identifying actual data and the atlases). The demo links above are hosted as GitHub pages, and use an external data source (those 62 DZI pyramids consist of a bit more than 1.6 million tiles - 256x256 pixel square images, which is quite typical, and occupy more than 4.3 gigabytes, which is actually smaller than normal, but it still isn't a good fit for hosting on GitHub).

Simpler, co-located case

For simplicity the demo dataset has its own co-located LocaliZoom installation too, this approach results in the simplest configuration file and implicitly avoids some possible pitfalls, like Cross-Origin Resource Sharing.

Of course LocaliZoom also has to find the image pyramids themselves, which brings us to the configuration.js file. Amongst other tasks, this small file is responsible for locating the actual pyramid files, based on the contents coming from the series descriptor.

A QuickNII (or VisuAlign) series descriptor refers to actual, local image files, residing next to the descriptor, and usually being in .png or .jpg format:

{
    "name": "Test series",
    [...]
    "slices": [
        {
            "filename": "14122_mPPC_BDA_s006.png", <-- existing file in the !Series folder (and .zip)

Clicking around in the example dataset shows what we actually have:

This is what the configuration file has to reproduce when asked to. It contains a transformSeries(series) function which allows preprocessing the entire series object (the QuickNII/VisuAlign JSON descriptor) after loading, and a locator object with actual functions for providing the URL of the series descriptor, .dzi files, tiles in the _files folder, and the two atlas files (.json and .pack).

transfromSeries() function

function transformSeries(series) {

The demo function does a convenience transformation: removes the extension from filename, so later the locators can simply append .tif, .dzi, and _files to it:

    for (const slice of series.slices) {
        slice.filename = slice.filename.substring(0, slice.filename.lastIndexOf("."));
    }

And a dirty hack happens too: knowing that the demo dataset is dark, outline and marker colors are set to something light (white and magenta). This is a quite non-standard step, but it's possible.

    document.getElementById("outline").value="#FFFFFF";
    document.getElementById("ancolor").value="#00FFFF";
    document.getElementById("nlcolor").value="#00FFFF";
}

locators object

const locators = {

SeriesLocator is expected to create an actual URL from a series identifier. Here the series URL parameter was a complete relative path (../!Series/visualign.json), and thus no actual transformation is done:

    SeriesLocator: series_id => series_id,

DZILocator is expected to create an actual URL from a section_id, which is actually the filename, from the series. As filename has been stripped from its .png extension earlier, this step really just appends some extensions to the identifier:

    DZILocator: section_id => `../${section_id}.tif/${section_id}.dzi`,

TileLocator is expected to create an actual URL of a tile. DZI pyramids simply look like this: something.dzi is accompanied by a something_files/ folder right next to it, where there are levels inside, also as folders (numbered from 0/), and inside those folders there are the actual tiles, like 0_0.png. The numbers are coming from the viewer, and the format of the tiles (.png here) comes from the DZI. As filename has been stripped from its .png extension earlier, this step also just merges the parameters together:

    TileLocator: (section_id, level, x, y, format) =>
                     `../${section_id}.tif/${section_id}_files/${level}/${x}_${y}.${format}`,

AtlasLocator is expected to create an actual URL for the atlas descriptor. As WHS_SD_Rat_v4_39um.json resides right next to the viewer, only the .json extension is added here:

    AtlasLocator: atlas_id => atlas_id + ".json",

AtlasVolumeLocator is expected to create an actual URL for the compressed atlas volume. As WHS_SD_Rat_v4_39um.pack resides right next to the viewer, only the .pack extension is added here:

    AtlasVolumeLocator: atlas_id => atlas_id + ".pack"
};

Example with remote data

A more real-life example is the one on GitHub pages, linked at the top of this page, like https://tevemadar.github.io/LocaliZoom/filmstripzoom.html?atlas=WHS_SD_Rat_v4_39um&series=https://data-proxy.ebrains.eu/api/v1/public/buckets/localizoom/!Series/quicknii.json&pyramids=https://data-proxy.ebrains.eu/api/v1/public/buckets/localizoom (this is the first one of the innocent-looking [demo] links on this page). The key difference is that LocaliZoom is hosted somewhere (https://tevemadar.github.io/LocaliZoom/filmstripzoom.html), and the dataset is hosted somewhere else. Here complete URL-s are used (similarly to the previous case, just there these were relative URL-s). In a real-life installation, specific to a certain website, some parts of the URL would be moved into the configuration file. The series descriptor (https://data-proxy.ebrains.eu/api/v1/public/buckets/localizoom/!Series/quicknii.json) and pyramids (new URL argument, https://data-proxy.ebrains.eu/api/v1/public/buckets/localizoom) are separated. This way one image series may have multiple alignments, and it's also possible to refer image series where we could not put our series descriptors simply because of the lack of write access to the given server in general or location in particular. The actual configuration.js is on GitHub this time, and it also contains jsdoc documentation.

TileLocator

Apart from the documentation part it has two new things: it tells that the URL parameters are actually available in an object called args, and the TileLocator makes use of it:

TileLocator: (section_id, level, x, y, format) =>
    `${args.pyramids}/${section_id}.tif/${section_id}_files`+
    `/${level}/${x}_${y}.${format}`

and that's it, what was the relative URL ../ in the previous example, became ${args.pyramids}/ now. Technically this configuration could be used for the co-located example too, via providing an extra parameter pyramids=...

Support

EBRAINS support in general (no EBRAINS registration is necessary). And there is an issue tracker on GitHub for bugs and features.

Acknowledgements

Localizoom is developed by the Neural Systems Laboratory at the Institute of Basic Medical Sciences, University of Oslo, Norway. Localizoom was developed with support from the EBRAINS infrastructure, and funding from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Framework Partnership Agreement No. 650003 (HBP FPA).

Dataset

In this example a copy of "subject 14122 mPPC BDA" is used from

Olsen, G. M., Hovde, K., Sakshaug, T., Sømme H., H., Monterotti, B., Laja, A., Reiten, I., Leergaard, T. B., & Witter, M. P. (2020). Anterogradely labeled axonal projections from the posterior parietal cortex in rat [Data set]. EBRAINS.

https://doi.org/10.25493/FKM4-ZCC

Theme

Water.css (dark)

Citation

[The plan is to get an RRID, and there may be some article coming too.]