dustmaps3d
🌌 An all-sky 3D dust extinction map based on Gaia and LAMOST
📄 Wang et al. (2025), An all-sky 3D dust map based on Gaia and LAMOST
📌 DOI: 10.12149/101620
📦 A Python package for easy access to the 3D dust map
📌 DOI: 10.12149/101619
📦 Installation
Install via pip:
pip install dustmaps3d
📦 Data File Instructions
⚠️ The package does not include the data file. A ~400MB model file will be automatically downloaded on first use from GitHub or NADC.
🚀 Auto Download Mechanism
-
When
dustmaps3d()is called, it will try to downloaddata_v3.fits.gz; -
After download, it will automatically extract the file to
data_v3.fitsand cache it locally; -
On future runs, the file will be read from the local cache without re-downloading.
-
✅ For international users, the primary source is: GitHub Releases
-
🌀 If GitHub download fails, it will automatically fallback to: NADC Data Center
On Chinese systems, the order is reversed — NADC is used as the primary source.
🌐 What if download fails?
If download fails (e.g. connect timeout), you can manually download and place the file in the cache directory:
-
Visit one of the following links:
🇨🇳 NADC Data Center (for China)
🌍 GitHub Releases (global) -
Download:
data_v3.fits.gz -
Extract to:
data_v3.fits -
Place the extracted file in the local cache directory (the location is printed on first use)
Example path (Windows):
C:\Users\<username>\AppData\Local\dustmaps3d\data_v3.fits
Example path (Linux/macOS):
/home/<username>/.local/share/dustmaps3d/data_v3.fits
🚀 Usage
from dustmaps3d import dustmaps3d
l = [120.0]
b = [30.0]
d = [1.5]
EBV, dust, sigma, max_d = dustmaps3d(l, b, d)
print(f"EBV: {EBV.values[0]:.4f} [mag]")
print(f"Dust: {dust.values[0]:.4f} [mag/kpc]")
print(f"Sigma: {sigma.values[0]:.4f} [mag]")
print(f"Max distance: {max_d.values[0]:.4f} kpc")
Batch example with FITS:
import numpy as np
from astropy.table import Table
from dustmaps3d import dustmaps3d
data = Table.read('input.fits')
l = data['l'].astype(float)
b = data['b'].astype(float)
d = data['d'].astype(float)
EBV, dust, sigma, max_d = dustmaps3d(l, b, d)
data['EBV_3d'] = EBV
data['dust'] = dust
data['sigma'] = sigma
data['max_distance'] = max_d
data.write('output.fits', overwrite=True)
⚙️ Tips for Advanced Users
To ensure broad compatibility and ease of use, the official dustmaps3d package makes certain design trade-offs that may come at the cost of peak performance.
If you have higher performance needs — such as support for multi-processing, command-line usage, or faster data loading and I/O — consider using the alternative implementation by SunnyHina:
👉 High-performance version: SunnyHina/dustmaps3d
This version adopts a more modern data loading architecture and is better suited for advanced users working with large-scale or batch processing workflows.
🧠 Function Description
dustmaps3d(l, b, d, n_process=None)
Estimates 3D dust extinction and related quantities for given galactic coordinates and distances.
| Input | Type | Description | Unit |
|---|---|---|---|
l |
np.ndarray | Galactic longitude | degrees |
b |
np.ndarray | Galactic latitude | degrees |
d |
np.ndarray | Distance | kpc |
Returns:
| Output | Type | Description | Unit |
|---|---|---|---|
EBV |
np.ndarray | E(B–V) extinction | mag |
dust |
np.ndarray | Dust density (d(EBV)/dx) | mag/kpc |
sigma |
np.ndarray | Estimated uncertainty in E(B–V) | mag |
max_d |
np.ndarray | Maximum reliable distance | kpc |
If
dcontainsNaN, it will be automatically replaced by the maximum reliable distance along that line of sight (max_d).If the input
dexceedsmax_d, it indicates the point lies beyond the model's reliable range. The returned values in this case are extrapolated and not guaranteed to be accurate.
⚡ Performance
- Fully vectorized and optimized with NumPy
- On a modern personal computer, evaluating 100 million stars takes only ~100 seconds
📜 Citation
If you use this model or the Python package, please cite both:
- Wang, T. (2025), An all-sky 3D dust map based on Gaia and LAMOST. DOI: 10.12149/101620
- dustmaps3d: A Python package for easy access to the 3D dust map. DOI: 10.12149/101619
🛠️ License
This project is open-source and distributed under the MIT License.
📫 Contact
If you have any questions, suggestions, or encounter issues using this package,
please feel free to contact the authors via GitHub issues or email.
- Prof. Yuan Haibo: yuanhb@bnu.edu.cn
- Wang Tao: wt@mail.bnu.edu.cn
1 maintainer
Metadata
1 maintainer
Release files for dustmaps3d 2.2.13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dustmaps3d-2.2.13.tar.gz | 9.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| dustmaps3d-2.2.13-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 19.2 kB
Release files / dustmaps3d-2.2.13.tar.gz
| Download URL | dustmaps3d-2.2.13.tar.gz |
|---|---|
| Size | 9.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ffbbb90a77cd1dc988089fe85f7f02b7225f2ee9dfbb3226eeb0124447f4948c
|
|
BLAKE2b-256 checksum How to use checksums |
13f7972bd8c3c61f30c77556bb1da25322bf7c1be4ef48160ee152964a8cefc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.3
|
Release files / dustmaps3d-2.2.13-py3-none-any.whl
| Download URL | dustmaps3d-2.2.13-py3-none-any.whl |
|---|---|
| Size | 9.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d15fc040d9eac3b55e56d81d4729c7434b6b75b3fb35fb80a044e1a97c635180
|
|
BLAKE2b-256 checksum How to use checksums |
c197279c584c57832b0b1e5527fa6b2857347f6ccb2b387b3868ce46269dd3d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.3
|
