See the stars in your image in 3D.

A photograph is flat. Two stars that sit side by side in your frame can be very different distances away. Distance Map takes the footprint of one solved image, asks Gaia DR3 for the stars inside it, converts each parallax to a distance, and draws the field as a 3D point cloud with you at the origin.

• 3D map from one image. Open a solved or solvable frame and the map builds automatically. Step 3
• Filters. Limit stars by Gaia G magnitude, distance, parallax quality, and count, then rebuild. Step 6
• 3D navigation. Orbit, pan, and zoom with the mouse, or jump to preset cameras. Step 5
• Cluster search. Find Cluster highlights the largest group of stars that share proper motion and, when available, parallax. Step 7
• Linked group views. A found group is emphasized in the 3D map, colored in the table, and circled on your image. Only Group filters to it. Step 8
• Depth tools. A parsec ruler along the line of sight and per-star parallax uncertainty lines. Step 9
• Tomography. Your image becomes a translucent slice that you drag through the star cloud. Step 10
• Globular cluster catalog. A wireframe sphere for 17 bundled globular clusters, and a display model that compacts a cluster in depth. Step 11
• Image export. Save the current 3D view as PNG, JPEG, or BMP. Step 12

Image

One image of a star field: XISF, FITS, TIFF, PNG, JPEG, or camera RAW. Distance Map works on one image at a time, not a folder.

Plate solving

An image with a valid celestial WCS works directly. Without one, CAst tries to solve it with local Gaia matching and, if you have entered an Astrometry API Key under Settings > Open Settings > General, astrometry.net at the same time.

Internet

The Gaia DR3 query needs a network connection. Results are cached, so rebuilding the same field is faster.

Graphics

The 3D view needs OpenGL. Without it, the table and log still fill in, but the 3D panel shows OpenGL 3D view is unavailable in this environment.

Good targets

Rich Milky Way fields, nearby open clusters, and associations show the most depth structure. Sparse high-latitude fields give fewer stars.

1. On the mode picker, click the Distance Map card (“Map catalog stars in 3D using their measured distances.”). From another mode, choose Mode > Distance Map instead. Mode > Choose Mode... brings the picker back.
2. Open your image. You can use either path below.
3. In the Select source image for Distance Map dialog, pick the file and click Open.

The build starts as soon as you choose the file. You do not need to click anything else.

While CAst works, Open changes to Building..., and the filters, Apply, View, Labels, Distance Ruler, Reset View, and Save are disabled. The Work Log at the bottom right and the status bar report each step:

1. CAst checks the image WCS. If it is missing or unusable, the log reads “Embedded WCS was unusable; recovering a plate solution.” and CAst solves the image.
2. It queries Gaia DR3 for stars at or below Mag Limit inside the solved field.
3. It rejects stars with low parallax quality, stars without a positive parallax, stars beyond Distance Limit, and stars outside the image rectangle. The log counts each rejection.
4. It keeps the brightest Max Stars survivors and draws them.

When the build is done, the status bar reads “Distance Map drew N star(s) from M Gaia source(s).” You now see four panels, which you can resize by dragging the dividers:

If the build fails, a Distance Map failed message explains why. The most common causes are an image that could not be solved and a failed network query. See Troubleshooting.

The map opens in the Orbit Overview camera: an angled view of the whole cloud. In most fields the stars form a long narrow cone pointing away from you, because the image covers a small patch of sky but a large range of distances.

• Left-drag: orbit around the center
• Mouse wheel: zoom in or out
• Middle-drag: pan
• Ctrl + left-drag: pan (moves the slice instead while Tomography is on)
• Ctrl + middle-drag: pan sideways and forward or back
• Ctrl + wheel: change the field of view
• Arrow keys: orbit, after you click the 3D view once

Preset cameras

1. Open the View list on the toolbar.
2. Choose Top-Down to look straight down on the cloud, Side View for a low side-on view, or Field Center for a closer view of the stars. Tomography Face-On is used with Tomography in Step 10.
3. After orbiting by hand, click Reset View to return to the selected preset.

Every preset aims at the middle of the visible stars, or at the highlighted group when one exists.

Labels

Labels is on by default and names up to 40 stars, the brightest ones. Turn it off to see the cloud without text. Once a group is highlighted, the labels switch to group members.

The four filters at the right end of the toolbar decide which Gaia stars reach the map. They only take effect when you rebuild.

1. Set Mag Limit to the faintest Gaia G magnitude you want. Default 17.0 mag.
2. Set Distance Limit to the farthest distance you want. Default 500.0 pc.
3. Set Min SNR, the minimum parallax divided by its error. Default 5.0. Set it to 0 to turn the quality cut off.
4. Set Max Stars, the number of stars drawn after filtering. Default 500.
5. Click Apply. CAst re-queries Gaia and rebuilds the map with the new values.

CAst saves these four values and uses them for the next image you open.

Ranges and the Gaia row cap are listed in Filters and defaults.

Stars born together drift through space together, so they share a proper motion and, if the cluster is close enough, a parallax. Find Cluster looks for the largest such group among the stars currently drawn.

1. Optional: click Advanced... to open Distance Map Cluster Detection. Choose a Preset: Default, Tight, Loose, Parallax Priority, or Custom. The text under the list describes each one. Click OK.
2. Click Find Cluster.
3. Read the Work Log line, for example “Highlighted 42 likely cluster member(s) using the Default preset via Lightweight (parallax-aware).”

After a successful search:

• 3D map. Members are drawn larger with a gold glow, and the cameras aim at them.
• Catalog Stars. Member rows turn gold.
• Field Image. Members are circled in their BP-RP color. Names appear when there are six or fewer.
• Toolbar. Find Cluster becomes Find All, and Only Group becomes available.

If nothing is found, CAst shows No cluster found: “Could not identify a likely cluster from the current map stars. Try loosening the preset or increasing the star count.” Try the Loose preset, raise Max Stars, or widen Distance Limit and click Apply.

The image, the table, and the 3D map share one group. What you do to the group shows up in all three.

1. Turn on Only Group. The 3D map and the Catalog Stars table now show members only. The image keeps its member circles.
2. Orbit the group and read the members' Parallax and Distance (pc) values in the table.
3. Turn Only Group off to see the group against the rest of the field again.
4. Click Find All to clear the group. The log reads “Returned to the full distance map selection.”

To try different detection settings, click Find All, change them in Advanced..., and click Find Cluster again. Clicking Apply also clears the group, because the map is rebuilt.

Distance Ruler

1. Turn on Distance Ruler.
2. A line appears along the image's line of sight, just beside the stars, from the nearest to the farthest visible star, with up to seven parsec ticks.
3. Switch View to Side View to read the depth of any part of the cloud against the ticks.

Parallax Uncertainty

1. Turn on Parallax Uncertainty.
2. Each star gets a pale line along its line of sight covering the distance range allowed by its parallax error. The log reports how many lines were drawn.
3. When a group is highlighted, only members get lines, which makes it easy to see whether the group is compact in depth or only looks compact.

Long lines mean the distance is poorly known. Short lines mean the depth is well measured. If most lines are long, raise Min SNR and click Apply.

Tomography puts your own image into the 3D scene as a translucent plane perpendicular to the line of sight, aligned with the image WCS. Moving it through the cloud shows which stars in your frame sit in front of or behind a given depth.

1. Click Tomography. The button stays pressed.
2. CAst places the slice halfway through the depth range of the stars and switches View to Tomography Face-On, so you look at the image straight on. The log records the slice depth in parsecs.
3. Hold Ctrl and left-drag up to push the slice farther away, or down to bring it closer. Dragging the full height of the view covers the whole depth range.
4. Switch View to Orbit Overview or Side View to see the slice from the side, inside the cloud.
5. Click Tomography again to remove the slice.

• Ctrl + left-drag up: slice moves away from you
• Ctrl + left-drag down: slice moves toward you

Tomography stays on when you click Apply. Opening a new image turns it off.

If your image shows one of the globular clusters in CAst's bundled list, you can draw the catalog's distance and size for it. Globular clusters are thousands of parsecs away, so their Gaia parallaxes are small and noisy.

1. Raise Distance Limit beyond the cluster's distance (for example 15000 pc), lower Min SNR, raise Max Stars, and click Apply.
2. Turn on Catalog Sphere. If a bundled cluster matches the field, a gold wireframe sphere appears at its catalog distance, and the log reads, for example, “Matched catalog cluster M13 (...)”. If none matches, the log says so.
3. With Model Cluster Depth on, the group members are placed inside that sphere at the catalog distance instead of being spread along their noisy parallax distances.
4. Turn Model Cluster Depth off to compare with the raw Gaia distances.

The list of clusters and the matching rules are in Globular cluster catalog.

1. Set up the camera, labels, ruler, and slice the way you want the figure to look.
2. Click Save.
3. In Save Distance Map Image, keep or change the suggested name, which is your image name followed by _distance_map.png, in the same folder as the image.
4. Choose PNG, JPEG, or BMP and click Save. The log records the saved path.

The file is a capture of the 3D view at its current size. Enlarge the 3D panel first for a larger image. Any extension other than PNG, JPEG, or BMP is replaced with .png.

The toolbar runs left to right in three groups: data and cluster controls, view controls, and filters.

Open

Choose a source image and build the map. Shows Building... while a build runs.

Find Cluster / Find All

Search the drawn stars for the largest co-moving group, or clear the group.

Available once a map exists.

Advanced...

Opens Distance Map Cluster Detection. Settings

Only Group

Show only group members in the 3D map and the table.

Available once a group exists. Off by default.

Model Cluster Depth

Place group members in a compact, center-weighted depth model. Detects a group automatically if you have not run Find Cluster.

On by default.

Parallax Uncertainty

Draw each star's distance interval along its line of sight.

Off by default.

Catalog Sphere

Draw a sphere for a matching bundled globular cluster.

Off by default.

View

Preset camera: Orbit Overview, Top-Down, Side View, Field Center, Tomography Face-On.

Default Orbit Overview.

Labels

Show up to 40 star names.

On by default.

Distance Ruler

Show a parsec scale along the line of sight.

Off by default.

Tomography

Show your image as a movable slice. Ctrl + left-drag moves it.

Off by default.

Reset View

Return the camera to the selected View preset.

Save

Save the current 3D view as PNG, JPEG, or BMP.

Mag Limit, Distance Limit, Max Stars, Min SNR

Filters for the Gaia query. Defaults and ranges

Apply

Re-query Gaia and rebuild the map with the current filters.

Available once an image is loaded.

Find Cluster, Tomography, Distance Ruler, Model Cluster Depth, Parallax Uncertainty, and Catalog Sphere stay disabled until a map with stars exists. Hover over any control in the app to see its tooltip.

CAst asks Gaia for up to four times Max Stars rows, and at least 500, so that enough stars remain after filtering. The filters run in this order:

1. Parallax SNR at or above Min SNR.
2. Positive parallax, and distance at or below Distance Limit.
3. Position inside the solved image rectangle, not just the circular query area.
4. Sort by G magnitude, then distance, and keep the first Max Stars.

The first lines of the Work Log after each build summarize what each step kept and rejected.

3D Distance Map

• Left-drag: orbit
• Ctrl + left-drag: pan, or move the Tomography slice while it is on
• Middle-drag: pan
• Ctrl + middle-drag: pan sideways and forward or back
• Wheel: zoom
• Ctrl + wheel: field of view
• Arrow keys: orbit (click the view first)

Field Image

• Wheel: zoom at the cursor
• Left-drag: pan

Application

• Ctrl + O: open an image (File > Open File)

The mode has no right-click menus. Clicking a table row or a star does not select it in the other panels. The panels are linked through the highlighted group.

Click Advanced... to open Distance Map Cluster Detection. Click OK to keep your changes or Cancel to discard them. The settings are saved and used by the next Find Cluster and by Model Cluster Depth.

All built-in presets use the Auto (recommended) backend.

Turn on Only Group automatically after detection

Turns on Only Group after every successful Find Cluster.

Off by default.

Show Expert Controls

Shows the four settings below. Changing any of them switches the preset to Custom. Choosing Custom opens them automatically.

Backend

Auto (recommended) uses scikit-learn's DBSCAN for 180 or more stars and a built-in version below that. Lightweight always uses the built-in version. Sklearn DBSCAN always uses scikit-learn, falling back to the built-in version if it is not installed.

Strictness

Scales the clustering radius. Lower values give tighter groups; higher values give looser groups.

Default 1.00, range 0.40 to 2.50.

Parallax

Auto uses parallax when enough stars have it. Require parallax always uses it and drops stars without it. Proper motion only ignores it.

Apply magnitude/color cleanup

Removes members that sit far from the others in color and absolute magnitude.

On by default.

Color

Gaia BP-RP, from blue (about -0.4) through white and orange to red (about 3.0). Green means BP-RP is missing.

Size

Brighter G magnitude gives a larger point, from 2 to 10 pixels.

Gold glow

A group member. Members are drawn at least 7 pixels.

Cyan point at the origin

You, the observer.

Pale lines along a sightline

Parallax Uncertainty intervals.

Light blue line with ticks

Distance Ruler, in parsecs.

Gold wireframe sphere

Catalog Sphere for a matched globular cluster.

Translucent image plane

The Tomography slice.

The cone shape of most maps is expected. Your image covers a small angle of sky, so the field widens with distance. Clumps strung out along the line of sight are often parallax scatter rather than real structure; Parallax Uncertainty shows which.

Parallax errors stretch a real cluster into a long streak along the line of sight. Model Cluster Depth redraws the group as a compact ball so you can read it as one object.

1. Members. If you ran Find Cluster, CAst uses that group. If not, it runs the same search with your current cluster settings. An automatically detected group is highlighted in gold and enables Only Group, but it is not circled on the Field Image and Find Cluster keeps its name.
2. Center. The distance is the inverse-variance weighted mean parallax of the members, converted to parsecs. With Catalog Sphere on and a matched cluster, the catalog distance and position are used.
3. Radius. From the angular spread of the members, limited to between 10 pc and 8% of the distance, or the visible core radius of a matched catalog cluster.
4. Placement. Each member stays on its own line of sight and is moved to a repeatable depth inside the sphere, weighted toward the center.

Catalog Sphere uses a bundled list of 17 globular clusters with catalog positions, distances, and radii:

M3, M4, M5, M10, M12, M13, M14, M15, M19, M22, M28, M53, M62, M79, M92, 47 Tuc, and Omega Cen.

A cluster matches when it lies within the field radius plus its visible core radius plus 0.35° of the field center or of the group's mean position, or when at least five map stars fall inside its visible core. The best match favors clusters inside the footprint, with more map stars nearby, and closer to the field center.

The sphere marks the visible core: about 28% of the catalog radius, capped at an angular radius of 0.28° and never less than 4 pc. When a group exists, its members are trimmed to stars near that core if at least five remain.

As Earth orbits the Sun, a nearby star shifts slightly against the background. Half of that shift is the parallax, ϖ. Gaia measures it in milliarcseconds (mas). Distance Map converts it with

distance (pc) = 1000 / ϖ (mas)

A star with a parallax of 10 mas is 100 pc away. A star with 1 mas is 1,000 pc away. Stars with zero or negative parallax get no distance and are dropped.

The parallax SNR is ϖ divided by its error σ. The Parallax Uncertainty line for each star runs from 1000 / (ϖ + σ) to 1000 / (ϖ − σ). Because the conversion is an inverse, a small error in a small parallax becomes a large error in distance, and the far end of the line grows quickly. That is why Min SNR defaults to 5: at that level 1000 / ϖ is a reasonable estimate. At lower SNR the simple inversion becomes biased.

Each star is then placed in 3D from its RA, Dec, and distance, in ICRS Cartesian coordinates in parsecs, with the observer at the origin.

Find Cluster uses DBSCAN, a density-based method that groups points with many close neighbors and leaves isolated points as noise.

1. Eligible stars. Drawn stars with proper motion in RA and Dec. At least five are needed.
2. Features. Proper motion in RA and Dec, plus parallax when it is used. With Parallax set to Auto, parallax is used when at least 35% of the stars (and at least six) have a positive parallax.
3. Scaling. Each feature is centered on its median and divided by 1.4826 times its median absolute deviation, so no single feature dominates.
4. Neighborhood. The minimum group core is the square root of the star count, between 5 and 12. The search radius is 1.25 times the 30th percentile of each star's distance to that many neighbors, multiplied by Strictness and kept between 0.25 and 2.4.
5. Result. The largest group is kept if it is at least the minimum core size.
6. Cleanup. With magnitude/color cleanup on, members are placed on a color versus absolute magnitude plot (M_G = G − 5 log₁₀(d) + 5), and outliers far from their neighbors are removed. The cleanup is skipped if it would remove more than 40% of the members.

The search only sees the stars currently drawn. Changing Max Stars, Distance Limit, or Min SNR changes the stars it can find.

Saved between sessions

The four filters, all cluster detection settings, Model Cluster Depth, Parallax Uncertainty, and Catalog Sphere.

Reset for each image

The group, Only Group, and Tomography.

Not saved

View, Labels, and Distance Ruler.

Switching modes

Leaving Distance Map clears the loaded image and map unless Keep mode memory when switching is on under Settings > Open Settings > General.