fusion-tools
Modular visualization and analysis dashboard creation for high-resolution microscopy images.
Installation
fusion-tools is deployed through PyPI and can be installed using:
$ pip install fusion-tools
Usage
fusion-tools is intended to bring some of the functionality found in FUSION to developers working with whole slide images (WSIs) stored locally.
One such example would be the Visualization and SlideMap class:
from fusion_tools.visualization import Visualization
from fusion_tools.components import SlideMap
vis_session = Visualization(
local_slides = [path_to_slide]
components = [
[
SlideMap()
]
]
)
vis_session.start()
The Visualization class lets users construct custom layouts of different tools by passing a list containing rows, columns, and tabs. (e.g. [ [column in row 1], [ [ tab 1 in column 2 in row 1, tab 2 in column 2 in row 1] ], [ [ column 1 in row 2 ] ] ] ).
By passing a list of paths to locally-stored whole slide images (WSIs), fusion-tools automatically generates a LocalTileServer which is bundled in with the Visualization session to allow for high-resolution image viewing.
from fusion_tools.visualization import Visualization
from fusion_tools.components import SlideMap, OverlayOptions, PropertyViewer
from fusion_tools.utils.shapes import load_aperio
path_to_slide = '/path/to/wsi.svs'
path_to_annotations = '/path/to/aperio_annotations.xml'
annotations = load_aperio(path_to_annotations)
vis_session = Visualization(
local_slides = [path_to_slide],
local_annotations = [annotations],
components = [
[
SlideMap(),
[
OverlayOptions(),
PropertyViewer()
]
]
]
)
vis_session.start()
You can also access remote tile servers (either through DSATileServer or CustomTileServer) as well as annotations stored on a Digital Slide Archive instance.
from fusion_tools.visualization import Visualization
from fusion_tools.handler.dsa_handler import DSAHandler
from fusion_tools.components import SlideMap
# Grabbing first item from demo DSA instance
base_url = 'https://demo.kitware.com/histomicstk/api/v1'
item_id = '5bbdeed1e629140048d01bcb'
# Starting the DSAHandler to grab information:
dsa_handler = DSAHandler(
girderApiUrl = base_url
)
# Checking how many annotations this item has:
#print('This item has the following annotations: ')
#print(dsa_handler.query_annotation_count(item=item_id).to_dict('records'))
vis_session = Visualization(
tileservers = [dsa_handler.get_tile_server(item_id)],
components = [
[
SlideMap()
]
]
)
vis_session.start()
You can also use some of segmentation components for adding labels and annotations to structures in the slide.
Creating annotations on top of structures
Applying labels to many structures at the same time
from fusion_tools.visualization import Visualization
from fusion_tools.handler.dsa_handler import DSAHandler
from fusion_tools.components import SlideMap, FeatureAnnotation, BulkLabels
# Grabbing first item from demo DSA instance
base_url = 'https://demo.kitware.com/histomicstk/api/v1'
item_id = '5bbdeed1e629140048d01bcb'
# Starting the DSAHandler to grab information:
dsa_handler = DSAHandler(
girderApiUrl = base_url
)
# Checking how many annotations this item has:
#print('This item has the following annotations: ')
#print(dsa_handler.query_annotation_count(item=item_id).to_dict('records'))
vis_session = Visualization(
tileservers = [dsa_handler.get_tile_server(item_id)],
components = [
[
SlideMap(),
[
FeatureAnnotation(
storage_path = os.getcwd()+'\\tests\\Test_Annotations\\',
labels_format = 'json',
annotations_format = 'rgb'
),
BulkLabels()
]
]
]
)
vis_session.start()
New in fusion-tools>2.0.0!
Now you can add multiple slides to a single visualization session and you can even view them side-by-side!
- By default, components in the same row are linked, or they can interact with each other through callbacks. This can be updated using the "linkage" kwarg when initializing a
Visualizationsession. - If two of the same types of components (e.g., two
SlideMapcomponents) are placed in the same row and "linkage" is set to "row", callbacks will not work. Beware!
from fusion_tools.visualization import Visualization
from fusion_tools.components import SlideMap, OverlayOptions, PropertyViewer, PropertyPlotter
from fusion_tools.handler.dsa_handler import DSAHandler
# Mixed types of slides and annotations
local_slide_list = ['slide1.tif','slide2.ome.tif','slide3.svs']
local_annotations_list = ['slide1_annotations.xml','slide2 annotations.json','annotations for slide3.h5ad']
dsa_handler = DSAHandler(
girderApiUrl = 'http://example_dsa_address.com/api/v1'
)
dsa_items_list = [
'item_uuid_1',
'item_uuid_2'
]
dsa_tileservers = [dsa_handler.get_tile_server(i) for i in dsa_items_list]
# Setting linkage to "col" to enable side-by-side visualization
vis_sess = Visualization(
local_slides = local_slide_list,
local_annotations = local_annotations_list,
tileservers = dsa_tileservers,
linkage = 'col',
components = [
[
[
SlideMap(),
OverlayOptions(),
PropertyViewer(),
PropertyPlotter()
],
[
SlideMap(),
OverlayOptions(),
PropertyViewer(),
PropertyPlotter()
]
]
],
app_options={'port': 8050}
)
vis_sess.start()
Examples:
For more examples including how to load specific types of spatial --omics datasets (10x Visium, VisiumHD, MxIF, etc.) see this dedicated example page:
https://spborder.github.io/fusion-welcome-page/
Contributing
Open to contributions. Feel free to submit a PR or post feature requests in Issues
Open Projects:
- Automated segmentation workflow for locally stored images (active-learning, SAM, etc.)
- Monitoring long-running model training/other external processes
License
fusion-tools was created by Samuel Border. It is licensed under the terms of the Apache 2.0 License
Citation
If you find this work useful in your own research, please consider citing:
@article{border2025fusion,
title={FUSION: A web-based application for in-depth exploration of multi-omics data with brightfield histology},
author={Border, Samuel P and Ferreira, Ricardo Melo and Lucarelli, Nicholas and Kumar, Suhas Katari Chaluva and Paul, Anindya S and Manthey, David and Barisoni, Laura and Levites Strekalova, Yulia A and Ray, Jessica and Cheng, Ying-Hua and others},
journal={Nature Communications},
volume={16},
number={1},
pages={8388},
year={2025},
publisher={Nature Publishing Group UK London}
}
1 maintainer
Metadata
1 maintainer
Release files for fusion-tools 3.6.93
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| fusion_tools-3.6.93.tar.gz | 263.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fusion_tools-3.6.93-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 546.5 kB
Release files / fusion_tools-3.6.93.tar.gz
| Download URL | fusion_tools-3.6.93.tar.gz |
|---|---|
| Size | 263.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6847353121ae56151d86a4c56a7ab4ab84bff6e223fb6e7894e9e402f01ac3e0
|
|
BLAKE2b-256 checksum How to use checksums |
3eae4ad043bb582974b92f9efd5d2df52c7fa4ad7ea3a212edf2bd81f9573ed2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.3 Linux/6.8.0-146-generic
|
Release files / fusion_tools-3.6.93-py3-none-any.whl
| Download URL | fusion_tools-3.6.93-py3-none-any.whl |
|---|---|
| Size | 283.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3034fdf05333203ef39591233dc1f53c2547c457b262c1eb5575ccbcce1a9350
|
|
BLAKE2b-256 checksum How to use checksums |
7191569a20c51f7c8d38c6a181ed47bc35d118e60d7382a741e9e6043d045450
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.3 Linux/6.8.0-146-generic
|
