UK Biobank atlas - mesh generation
Generate meshes using the UK Biobank atlas (https://www.cardiacatlas.org/biventricular-modes/)
Install
Install with pip
python3 -m pip install ukb-atlas
or (latest version)
python3 -m pip install git+https://github.com/ComputationalPhysiology/ukb-atlas
or similarly with pipx
pipx install ukb-atlas
or (latest version)
pipx install git+https://github.com/ComputationalPhysiology/ukb-atlas.git
Quick start
To generate surfaces from the UK Biobank atlas, run the following command
$ ukb-atlas surf data --mode -1 --std 1.5 --case ED
INFO:ukb.atlas:Generating points from /root/.ukb/UKBRVLV.h5
INFO:ukb.atlas:Using mode -1 and std 1.5
INFO:ukb.surface:Saved data/LV_ENDO_ED.stl
INFO:ukb.surface:Saved data/RV_SEPTUM_ED.stl
INFO:ukb.surface:Saved data/RV_FREEWALL_ED.stl
INFO:ukb.surface:Saved data/LV_EPI_ED.stl
INFO:ukb.surface:Saved data/RV_EPI_ED.stl
INFO:ukb.surface:Saved data/MV_ED.stl
INFO:ukb.surface:Saved data/AV_ED.stl
INFO:ukb.surface:Saved data/TV_ED.stl
INFO:ukb.surface:Saved data/PV_ED.stl
Each STL file is one region of the biventricular template. The file data/surfaces.json records
which files make up each surface of the mesh: LV_ENDO, RV_ENDO (RV septum and free wall),
EPI (LV and RV epicardium), and the valve rims MV, AV, TV and PV.
Now we can generate a mesh from these surfaces
$ ukb-atlas mesh data
INFO:ukb.mesh:Creating mesh for ED with char_length_max=5.0, char_length_min=5.0, order=1
INFO:ukb.mesh:Created mesh data/ED.msh
The mesh has the physical surfaces LV_ENDO, RV_ENDO, EPI, MV, AV, TV and PV, and the
physical volume Wall.
Now we can also create a mesh without the outflow tracts using the cilp command
$ ukb-atlas clip data
ukb-atlas clip data
INFO:ukb.clip:Folder: data
INFO:ukb.clip:Case: ED
INFO:ukb.clip:Origin: [-13.612554383622273, 18.55767189380559, 15.135103714006394]
INFO:ukb.clip:Normal: [-0.7160843664428893, 0.544394641424108, 0.4368725838557541]
INFO:ukb.clip:Reading data/LV_ENDO_ED.stl
Warning: PLY writer doesn't support multidimensional point data yet. Skipping Normals.
Warning: PLY doesn't support 64-bit integers. Casting down to 32-bit.
INFO:ukb.clip:Saved data/lv_clipped.ply
INFO:ukb.clip:Reading data/RV_SEPTUM_ED.stl, data/RV_FREEWALL_ED.stl
INFO:ukb.clip:Saving data/rv_clipped.ply
Warning: PLY writer doesn't support multidimensional point data yet. Skipping Normals.
Warning: PLY doesn't support 64-bit integers. Casting down to 32-bit.
INFO:ukb.clip:Reading data/LV_EPI_ED.stl, data/RV_EPI_ED.stl
INFO:ukb.clip:Saving data/epi_clipped.ply
Warning: PLY writer doesn't support multidimensional point data yet. Skipping Normals.
Warning: PLY doesn't support 64-bit integers. Casting down to 32-bit.
and then create a mesh from the clipped surfaces
$ ukb-atlas mesh data --clipped
INFO:ukb.mesh:Creating clipped mesh for ED with char_length_max=5.0, char_length_min=5.0, order=1
INFO:ukb.mesh:Created mesh data/ED_clipped.msh
The clipped mesh has the physical surfaces LV_ENDO, RV_ENDO, EPI and BASE, and the physical
volume Wall.
Geometries
surf takes a --geometry (-g) option, and mesh builds whichever geometry surf wrote:
| Geometry | Physical surfaces | Physical volumes |
|---|---|---|
biv (default) |
LV_ENDO, RV_ENDO, EPI, MV, AV, TV, PV |
Wall |
biv-closed |
as biv, plus MV_CAP, AV_CAP, TV_CAP, PV_CAP |
Wall, LV_CAVITY, RV_CAVITY |
lv |
LV_ENDO, EPI, RV_SEPTUM, SEPTAL_BRIDGE, MV, AV |
Wall |
lv-closed |
as lv, plus MV_CAP, AV_CAP |
Wall, LV_CAVITY |
MV, AV, TV and PV are the rims where the endocardium and epicardium meet at each valve. In
the closed geometries each valve opening is also closed by a cap (*_CAP), so the LV
(LV_ENDO + MV_CAP + AV_CAP) and RV (RV_ENDO + TV_CAP + PV_CAP) cavities are closed
surfaces. The cavities are meshed as their own volumes, sharing nodes with the wall at the
endocardium. The LV-only geometries keep the outflow tract; the LV wall is closed on the RV side by
the RV septal surface (RV_SEPTUM) and a surface through the wall along the RV insertion
(SEPTAL_BRIDGE), and its EPI is the LV epicardium only.
$ ukb-atlas surf data -g biv-closed
$ ukb-atlas mesh data
clip only supports the biv geometries.
Higher order meshes
mesh takes an --order option for elements of higher order, e.g. quadratic tetrahedra with
$ ukb-atlas mesh data --order 2
The nodes of the higher order elements are placed on the surfaces. Since the surfaces are triangulations this can invert elements, so they are untangled with the high order optimizer of gmsh. This is fast for order 2, but can take a few minutes for order 3. The optimizer sometimes aborts the whole process, so meshes of higher order are created in a separate process and retried if it fails.
The nodes of the higher order elements can only be as accurate as the surfaces they are placed on,
and the triangles of the atlas have sides of 3-4 mm. With surf --refine N each triangle is split
into four N times, and the new nodes are placed on a smooth surface through the nodes of the
atlas: the template is a subdivision of the faces of a coarse control mesh into 4 x 4 quads, so on
each face the atlas nodes are a regular grid, which we interpolate with a cubic spline (see
ukb.smooth). The valve rims and caps, and the septal bridge, are not on the control mesh and are
split at the midpoints of their edges. With quadratic elements this lets you use much coarser
meshes, e.g.
$ ukb-atlas surf data -g lv-closed --refine 2
$ ukb-atlas mesh data --order 2 --char_length_max 10 --char_length_min 10
gives a volume of the LV cavity within 0.01% of the smooth surface with fewer than 4000 cells in the wall, while linear elements of size 2 mm (60000 cells in the wall) are 0.1% off.
We can also export labelled point clouds directly from the atlas using the points command
$ ukb-atlas points data --mode -1 --std 1.5 --case both
INFO:ukb.atlas:Generating points from /root/.ukb/UKBRVLV.h5
INFO:ukb.atlas:Using mode -1 and std 1.5
INFO:ukb.pointcloud:Saved data/ED_pointcloud.tsv
INFO:ukb.pointcloud:Saved data/ES_pointcloud.tsv
This generates tab-separated files (ED_pointcloud.tsv, ES_pointcloud.tsv) with columns x, y, z, label, and region for every node of the biventricular template. The labels are 1-4 for the valve rims
(MV, AV, TV, PV), 5 LV_ENDO, 6 RV_SEPTUM, 7 RV_FREEWALL, 8 LV_EPI, 9
RV_EPI, and 10-13 for the valve centre nodes (MV_CAP, AV_CAP, TV_CAP, PV_CAP).
The triangulation and region labels come from the
biv-me template (Apache-2.0), vendored in
src/ukb/data/biv-me.
Usage
There are three main commands:
surf- Extract surfaces from the atlas and save them in the specified directory as STL filesclip- Clip the surfaces to remove e.g the outflow tractsmesh- Generate mesh from the surfaces
usage: ukb-atlas [-h] {surf,clip,mesh} ...
UKB-atlas This is a command line interface for extracting surfaces and generating Bi-ventricular meshes from the UK Biobank atlas: https://www.cardiacatlas.org/biventricular-modes/
positional arguments:
{surf,clip,mesh}
surf Extract surfaces from the atlas
clip Clip the surfaces
mesh Generate mesh from the surfaces
options:
-h, --help show this help message and exit
Citing
If you use this tool to create meshes please cite
@software{Finsberg_fenics-beat_2024,
author = {Henrik Finsberg and Lisa R Pankewitz},
doi = {10.5281/zenodo.13927883},
title = {UK Biobank atlas - mesh generation},
url = {https://github.com/ComputationalPhysiology/ukb-atlas},
version = {0.1.0},
year = {2024}
}
The templates used to generate the meshes are described where developed as part of the following publication (so please cite this paper if you use the templates)
@article{PANKEWITZ2024103091,
title = {A universal biventricular coordinate system incorporating valve annuli: Validation in congenital heart disease},
journal = {Medical Image Analysis},
volume = {93},
pages = {103091},
year = {2024},
issn = {1361-8415},
doi = {https://doi.org/10.1016/j.media.2024.103091},
url = {https://www.sciencedirect.com/science/article/pii/S1361841524000161},
author = {Lisa R Pankewitz and Kristian G Hustad and Sachin Govil and James C Perry and Sanjeet Hegde and Renxiang Tang and Jeffrey H Omens and Alistair A Young and Andrew D McCulloch and Hermenegild J Arevalo},
keywords = {Cardiac geometry, Coordinates, Congenital Heart Disease, Mapping},
}
License
MIT
Metadata
Release files for ukb-atlas 2.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ukb_atlas-2.2.0.tar.gz | 146.3 kB | With provenance | Details for ukb_atlas-2.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ukb_atlas-2.2.0-py3-none-any.whl | Python 3 | none | any | Details for ukb_atlas-2.2.0-py3-none-any.whl |
Total release size: 280.8 kB
Release files / ukb_atlas-2.2.0.tar.gz
| Download URL | ukb_atlas-2.2.0.tar.gz |
|---|---|
| Size | 146.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8634ebbdd9de4c803c72dd5468bdfd90bc3e8eb809e96b212091df5c9aea5879
|
|
BLAKE2b-256 checksum How to use checksums |
cb0ebfb3a72fcc4625631668858fcd57c8cf877f3b4bdcb7eaf95fcf4c2c7c90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / ukb_atlas-2.2.0-py3-none-any.whl
| Download URL | ukb_atlas-2.2.0-py3-none-any.whl |
|---|---|
| Size | 134.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d833d0cc8ede8d1fcca7cfd6a75daadb6e21f3be7392e09d7c5c6b61744a12f
|
|
BLAKE2b-256 checksum How to use checksums |
3c4ba5334430abc91d3810589ecccebf44ac97b39ad914866c282285725c7f77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for ukb-atlas 2.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ukb_atlas-2.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.