DeepSpatial is a package for true 3D reconstruction of spatial omics tissues from serial 2D slices, built with PyTorch and designed to work smoothly with AnnData/Scanpy workflows.

3D spatial omics reconstruction

DeepSpatial provides an end-to-end framework for learning continuous 3D tissue representations:

• Reconstructs missing biological structure between adjacent sections.
• Jointly models spatial coordinates, gene expression, and cell identities.
• Supports large-scale training and sampling with GPU acceleration.
• Produces outputs that can be directly used in downstream single-cell/spatial analysis.

The package exposes a high-level API (DeepSpatial) for data setup, model training, and 3D reconstruction with minimal boilerplate.

Installation

Recommended (PyPI):

pip install deepspatial

From source (development):

git clone https://github.com/yyh030806/DeepSpatial.git
cd DeepSpatial
pip install -e .

If you use GPU, install a PyTorch build matching your CUDA version.

Quick start

1. Download an example dataset first: Google Drive dataset folder

   Then place files under data/merfish_mouse_hypothalamus/.

2. Run DeepSpatial:

import glob
import scanpy as sc
import deepspatial as ds

adatas = [
    sc.read_h5ad(p)
    for p in sorted(glob.glob("data/merfish_mouse_hypothalamus/merfish_*.h5ad"))
]

model = ds.DeepSpatial()
model.setup_data(adatas)
model.build_model()
model.fit(max_epochs=100)

adata_3d = model.reconstruct_full_volume(adatas, thickness=10.0)

Resources

• Documentation, tutorials, and API reference: https://yyh030806.github.io/DeepSpatial/docs/
• Homepage: https://yyh030806.github.io/DeepSpatial/
• Bug reports and feature requests: https://github.com/yyh030806/DeepSpatial/issues

Citation

If you use DeepSpatial in your research, please cite:

@article {yang2026deepspatial,
	author = {Yang, Yuhang and Luo, Yiming and Zhang, Kai and Bu, Yonggan and Xia, Zheng and Peng, Haoxin and Yan, Rui and Liu, Qi and Chen, Yang and Shen, Lin and Chen, Enhong},
	title = {Reconstructing True 3D Spatial Omics at Single-Cell Resolution},
	year = {2026},
	doi = {10.64898/2026.04.28.721395},
	journal = {bioRxiv}
}

License

DeepSpatial is released under the MIT License.