A Discovery Tool for Astronomical Research
StarGateVR: CSV Input Data Format Reference
– Updated February 2026
How StarGateVR reads, interprets, and enriches your star data files.
Summary
StarGateVR accepts any well-formed CSV file. Every column becomes an axis you can map to X, Y, Z, Color, or Brightness in VR. The system handles strings, floats, and integers. However, if your CSV contains certain recognized column names (like ra, dec, parallax), the system will automatically compute derived quantities and set up meaningful default views — putting you inside a 3D star field without any configuration.
Basic Format Requirements
- • Delimiter: Comma (,) only
• Header row: Required. First line must contain column names.
• Encoding: UTF-8 (standard). BOM detection supported.
• Row consistency: Every row must have the same number of columns as the header. Mismatched rows cause parsing to stop.
• Whitespace: Column names and cell values are trimmed automatically.
• Missing values: NULL, NaN, empty cells → stored as 0.0 for numeric columns, “” for string columns.
Supported File Formats (Auto-Converted)
In addition to .csv, StarGateVR can accept these formats, which are converted to CSV server-side before loading:
- • VOTable: .vot, .xml, .vot.gz, .xml.gz, .votable.gz
• FITS: .fits, .fit, .fits.gz, .fit.gz, .fts.gz
• JSON: .json
Data Types
All columns default to numeric (double) except source_id, which is always stored as a string regardless of content. Prefixes gaia_dr3_, Gaia_DR3_, and # are automatically stripped. If any non-numeric values are found in a column during parsing, the entire column is converted to string type. String columns are indexed internally (each unique value gets a numeric index) for axis mapping, up to a limit of 100 unique values — beyond that, the column falls back to row-index numbering.
Recognized Column Names
StarGateVR recognizes Gaia-style column names. If your CSV uses different naming conventions, the system automatically renames them to canonical forms:
- • rv → radial_velocity
• rv_error → radial_velocity_error
• magnitude → phot_g_mean_mag
• GMAG / gmag → phot_g_mean_mag
• RMAG / rmag → phot_rp_mean_mag
• BMAG / bmag → phot_bp_mean_mag
• G_mag → phot_g_mean_mag (VOSA SED format)
• BP_mag → phot_bp_mean_mag (VOSA SED format)
• RP_mag → phot_rp_mean_mag (VOSA SED format)
• BP → phot_bp_mean_mag
• RP → phot_rp_mean_mag
• BP_RP / bp_rp_mag → bp_rp
• PLX → parallax
• ABSG → abs_mag
• X, Y, Z → x, y, z (uppercase to lowercase)
• U, V, W → u, v, w (uppercase to lowercase)
Renaming only occurs if the target name doesn’t already exist, so your data is never silently overwritten.
What Gets Auto-Computed (and When)
When StarGateVR detects certain columns, it automatically derives additional quantities so you can immediately explore your data in 3D. The computation chain runs in this order:
1. Distance ↔ Parallax
• parallax only → dist = 1000 / parallax (parsecs from milliarcseconds)
• dist only → parallax = 1000 / dist
• Both present → fills in missing rows only (where one is 0.0 and the other isn’t)
2. Galactic Coordinates (l, b) from RA, Dec
• ra + dec → l and b (galactic longitude/latitude)
• Only computes for rows where existing l and b are both near zero (< 0.0001). Existing non-zero values are preserved.
3. Absolute Magnitude
• phot_g_mean_mag + dist → abs_mag = G – 5 × log₁₀(dist) + 5
• Only fills rows where current abs_mag is 0.0 or 25.0 (the missing-data placeholder). Existing valid values are preserved.
4. 3D Position (x, y, z) from Galactic Coordinates
• l + b + dist → x, y, z (Cartesian galactic coordinates)
• Key rule: If x, y, z columns already exist in your CSV, they are used as-is — no recomputation.
5. 3D Velocity (u, v, w) from Proper Motion
• pmra + pmdec + radial_velocity + ra + dec + dist → u, v, w (space velocities)
• If u, v, w already exist, only rows with u == 0.0 are recomputed. Rows with radial_velocity == 0.0 get u=v=w=0.0 (treated as stationary).
6. Color Index
• phot_bp_mean_mag + phot_rp_mean_mag → bp_rp = BP – RP (preferred)
• phot_g_mean_mag + phot_rp_mean_mag → gp_rp = G – RP (fallback)
• bp_rp or gp_rp is renamed to color_index. If color_index already exists, missing values (0.0) are backfilled.
7. Synthetic Columns (Always Added)
• zero — every row is 0.0 (used as a “flat” axis, e.g., for 2D views like the HR diagram)
• one — every row is 1.0
The Override Principle
Existing non-zero values always take priority over computed values. If your CSV already contains a column that StarGateVR would normally compute, the provided values are used. Computation only fills in gaps (rows where the value is 0.0 or missing). This gives you full control: include pre-computed columns in your CSV and StarGateVR won’t second-guess them.
Default 3D Views
When StarGateVR detects the right combination of columns, it sets up default axis mappings automatically:
Full Stellar View (preferred default) — requires x, y, z + color_index + abs_mag:
• X → x (galactic Cartesian), Y → y, Z → z
• Color → color_index, Brightness → abs_mag, Display → source_id
HR Diagram Preset — requires color_index + abs_mag:
• X → color_index, Y → zero (flat), Z → abs_mag
• Color → color_index, Brightness → abs_mag
HR-Teff Preset (SED-fitted data) — requires Teff/log_Teff + Lbol/log_Lbol:
• X → log_Teff (preferred) or inv_Teff or Teff
• Y → logg or mass or zero
• Z → log_Lbol (preferred) or Lbol
Generic Fallback — if no recognized stellar columns are found, axes are mapped to the first six columns in order: X=col0, Y=col1, Z=col2, Color=col3, Brightness=col4, Display=col5.
Magnitude Columns (Auto-Detected, Axis-Flipped)
Columns identified as magnitudes have their axes automatically inverted so that brighter = higher in the visualization (astronomically correct: lower magnitude = brighter). A column is treated as a magnitude if its name is in the recognized list (abs_mag, phot_g_mean_mag, phot_bp_mean_mag, phot_rp_mean_mag, bp_rp, gp_rp, color_index, grvs_mag, jmag, hmag, kmag, w1mag–w4mag, gmag, rmag, bmag, nuvmag, fuvmag, and their error variants) or if its name contains the substring _mag.
Legacy Cleanup: All-Zero Column Dropping
For backward compatibility with older Gaia query templates that included placeholder columns like 0 as l, 0 as X, 0 as abs_mag, the system checks whether all of the following columns exist: l, b, x, y, z, u, v, w, abs_mag. If any of these columns contains nothing but zeros, it is silently dropped so that fresh values can be computed from the actual data.
The Zero Convention
Throughout StarGateVR, 0.0 in a numeric column is treated as “no data”:
• phot_g_mean_mag == 0.0 → replaced with 25.0 (impossibly faint placeholder)
• color_index == 0.0 → treated as missing, backfilled if possible
• radial_velocity == 0.0 → star treated as stationary
• u == 0.0 → triggers recomputation from proper motion if available
• Zeros are excluded from min/max axis scaling calculations
This is a known limitation: genuine measured values of exactly 0.0 will be treated as missing. In practice this rarely affects astronomical quantities.
Quick Reference: Minimum Columns for Each Feature
• Basic 3D scatter plot → any 3+ numeric columns
• Stellar 3D position → ra, dec, parallax (xyz computed) OR x, y, z directly
• Space velocities → pmra, pmdec, radial_velocity, ra, dec, dist (uvw computed) OR u, v, w directly
• HR Diagram → color_index (or bp_rp) + abs_mag (or phot_g_mean_mag + parallax/dist)
• HR-Teff Diagram → Teff/log_Teff + Lbol/log_Lbol
• Color mapping → any numeric column (or string column with ≤100 unique values)
• Star identification → source_id (displayed on hover/selection)
Example: Minimal Gaia-Style CSV
source_id,ra,dec,parallax,parallax_error,pmra,pmdec,radial_velocity,phot_g_mean_mag,phot_bp_mean_mag,phot_rp_mean_mag
2061465177983983104,280.154,38.612,130.23,0.02,-200.94,286.23,-13.9,0.03,0.15,-0.14
From this input, StarGateVR will automatically compute: dist, l, b, x, y, z, abs_mag, bp_rp → color_index, u, v, w, zero, one — and drop you into a 3D stellar neighborhood with HR diagram ready to go.
Example: Custom Data (Non-Stellar)
sample_id,temperature,pressure,density,classification
A001,1523.4,2.1,0.034,Type-A
A002,1897.2,3.4,0.041,Type-B
StarGateVR will map X=temperature, Y=pressure, Z=density, Color=classification (indexed as string categories). No stellar computations are triggered because no recognized column names are present.
This reference describes the behavior of DataGate.cs as of February 2026.