What's In My... IMAGE - setiastro/setiastrosuitepro GitHub Wiki

What’s In My Image (WIMI) — User & Dev Guide

WIMI is a PyQt-based tool for exploring astronomical images: load an image, solve for WCS, search SIMBAD/VizieR/MAST within a user-defined region, visualize results, annotate, and export products (annotated images, collages, 3D distance plots, H–R diagrams, and plate-solved FITS).

Quick Start

  1. Load an image (FITS/PNG/JPG/TIFF/XISF) → Left panel › Load Image File or Load from View.
  2. (Optional) AutoStretch to enhance contrast for display only.
  3. Define a search region: Shift+Click and drag in the main image (circle).
  4. Query SIMBAD (or Advanced: VizieR / MAST).
  5. Browse results in the table, click to highlight, double-click to open external pages.
  6. Annotate as needed; save annotated image or Save Plate-Solved FITS.
  7. Try 3D Distance Model or H–R Diagram for advanced visualization.

UI Overview

Left Panel

  • Logo
  • Load from View / Load Image File / AutoStretch
  • Search Region hint (“Shift+Click…”)
  • Query SIMBAD (+ Legend)
  • Show Object Names (overlay on image) & Clear Results
  • Show Visible Objects Only (brightness filter) & Save CSV
  • Advanced Search (toggle side panel)
  • Status label
  • Copy RA/Dec to Clipboard & Settings (wrench)
  • Save Plate Solved FITS
  • RA/Dec/Orientation readouts
  • Mini Preview (with green viewport box, draggable navigation)

Right Panel

  • Zoom In / Zoom Out
  • Main Preview (QGraphicsView + scene, anti-aliased, under-mouse zoom anchor)
  • Show Annotation Tools / Save Annotated Image / Save Collage / 3D Distance Model / H–R Diagram
  • Object Count + “Right Click a Row for More Options”
  • Results Table (RA, Dec, Name, Diameter, Type, Long Type, Redshift, Distance (GLy))
  • Annotation Tools (toggleable section)

Advanced Search Panel (side)

  • Object Type Tree (SIMBAD otype → description, color-coded by category)

    • Parent check toggles all children
    • Toggle All, Save List…, Load List…

  • Search Defined Region / Search Entire Image

  • Caution – Deep VizieR Search (large datasets)

  • Search M.A.S.T Database (Hubble/JWST/Spitzer/TESS etc.)

Core Concepts & Data Flow

Image I/O & Display

  • Loads arrays via load_image() (FITS / XISF path includes optional metadata extraction).

  • Converts floats in [0..1] → 8-bit RGB for display (mono images replicated to 3 channels).

  • AutoStretch:

    • Mono: stretch_mono_image(...)
    • Color: stretch_color_image(..., linked=True)
    • Toggled via the same button (stores/restores original for display).

WCS Handling

  • Sources for WCS header (first match wins):

    1. metadata['wcs_header']
    2. metadata['original_header'] that already contains WCS
    3. XISF metadata converted to a FITS-like header
    4. Fallback: unified solver → ASTAP (seeded if possible) then Astrometry.net

  • Headers are sanitized (_sanitize_wcs_header) to fix types/SIP inconsistencies.

  • WCS initializes:

    • self.wcs = WCS(header, naxis=2, relax=True)
    • pixscale computed (arcsec/px)
    • center_ra/dec set
    • orientation from CROTA2 or calculated via CD/PC matrix (calculate_orientation)

Plate Solving

  • Shared solver path (doc-level): plate_solve_doc_inplace (ASTAP → Astrometry.net).

  • Manual ASTAP path (plate_solve_image):

    • Writes normalized temp FITS
    • Seeds ASTAP with RA/SPD/scale when possible
    • Merges .wcs file results into header, coerces types, ensures SIP pairs
    • Rebuilds FITS header and re-initializes WCS

  • Astrometry.net helpers:

    • Login / Upload (handles XISF→TIFF convert), Poll submission & calibration
    • Retrieve & apply WCS FITS header

  • Save Plate-Solved FITS:

    • Choose 8/16/32-bit
    • Mono vs RGB cube handling
    • Combines original header with wcs.to_header(relax=True) and writes

Region Definition & Queries

Region of Interest (ROI)

  • Shift+Click to set circle center; drag to size → circle_center, circle_radius (px)

  • Radius conversions:

    • arcmin for UI/status: radius_px * pixscale / 60
    • degrees for services: radius_px * pixscale / 3600

SIMBAD

  • TAP query to basic within ROI (ra, dec, name, otype, redshift, major axis)

  • Optional star-only enrichment via sim-sam: pulls B, V, parallax, spectral type

  • Distances:

    • Parallax → distance (pc→ly), stored as GLy for consistency
    • Else redshift → comoving distance (calculate_comoving_distance)

  • Table populated and query_results cached for plots; items include:

    {
  ra, dec, name, diameter, short_type, long_type,
  redshift, comoving_distance, source,
  Bmag, Vmag, parallax_mas, spectral_type, absolute_mag
}

VizieR (Deep Search)

  • Prioritizes spectroscopic redshift surveys (2MRS, 6dF, SDSS DR12, 2dFGRS, GAMA)
  • Adds meta catalogs (GLADE+, HyperLEDA, PSCz) and wide surveys (2MASS, Gaia, UCAC4, Pan-STARRS)
  • Robust parsing of cz, z, zhelio, zcmb, zph, or Plx
  • Deduping heuristic across catalogs; results pushed to table & preview

MAST

  • Cone search via Mast.Caom.Cone on ROI center+radius
  • Shows selected fields (RA/Dec, target, instrument, data URL)
  • Results integrated into table + preview (source = “Mast”)

Results Table & Interactions

  • Sorting enabled; “Objects Found” label autoupdates.
  • Right-click a row → Open Website, Zoom to Object, Copy Object Information.
  • Single-click a row selects/highlights object in the main view.
  • Double-click opens external source: SIMBAD, NED (for VizieR cases), or MAST portal.
  • Save CSV exports the table as-is.

Annotations & Exports

Tools

  • Ellipse, Rectangle, Arrow, Freehand (Lasso), Celestial Compass, Text
  • Select Color / Select Font
  • Undo, Clear Annotations, Delete Selected Object
  • Show/Hide Object Names overlay

Save Annotated Image

  • Save Full or Save Cropped (current viewport) as JPG/PNG/TIFF
  • Search circle is temporarily hidden for a clean export

Save Collage of Objects

  • Grid of 128×128 patches centered on each object
  • User picks label lines: Name, RA/Dec, short/long type, redshift, comoving distance
  • Dynamic spacing based on chosen fields; exported as an image

Advanced Visualizations

3D Distance Model

  • Plotly 3D: sky plane (grayscale surface or RGB “point plane”) + objects in Z

  • Z axis from distance:

    • Logarithmic (log10(ly)) or Linear
    • Range: Default, Min–Max, or Custom [z_min, z_max]
    • Optional reverse Z and connector lines

  • Object color:

    • Image-Based (local color patch), Legend Color, or Solid Custom

  • Outputs HTML with embedded Plotly; click points to open SIMBAD; sidebar lists objects

H–R Diagram

  • B–V (x) vs Absolute V (y), reversed Y axis

  • Colors:

    • Realistic blackbody via kelvin_to_rgb(T) or Solid custom

  • Optional image background (diagram)

  • Adds radius isochrones (R = 0.01…1000 R⊙) as dashed guides

  • Optional Sun marker

  • Exports clickable HTML (stars link to SIMBAD) + sidebar list

Visibility Filter

  • Show Visible Objects Only:

    • Computes median and std dev from a grayscale conversion of the display image (OpenCV)
    • Threshold = median + n * std_dev (n = 0.2 default)
    • For each marker, samples an 8×8 neighborhood brightness; keeps only those over threshold
    • Updates results + redraws markers

Settings

Settings Dialog

  • Max Results (1 … 100000)
  • Marker Style: Circle / Crosshair
  • Force Blind Solve: temporarily set seed mode = none and solve (updates WCS if successful)

Paths

  • ASTAP executable path saved under paths/astap (legacy key migrated automatically)

Shortcuts & Gestures

  • Ctrl+Click: add annotation using the active tool
  • Shift+Click (drag): define/resize search circle
  • Alt+Click + drag: measure angular separation (dashed ruler + DMS label)
  • Mouse wheel: zoom; Drag: pan
  • Double-click marker: open SIMBAD/VizieR/MAST entry
  • Right-click table row: open/zoom/copy
  • Mini preview: click/drag to pan main view; green box shows current viewport

Externals & Networking

  • SIMBAD: TAP on basic, plus sim-sam for star magnitudes/parallax/spec types
  • VizieR: multi-catalog queries prioritized to redshift surveys, with dedupe
  • MAST: CAOM cone search
  • ASTAP: local plate solver (seeded or blind), merges .wcs output
  • Astrometry.net: login/upload/poll/apply WCS workflow as a fallback

Note: Network errors are handled with retries and user-friendly messages where practical.

Algorithms & Helpers

  • kelvin_to_rgb(T): Tanner Helland–style approximation to sRGB CSS rgb(r,g,b)

  • AutoStretch / Unstretch: per-channel median-based curve (linked option for color)

  • Coordinate helpers:

    • Pixel ↔ RA/Dec via Astropy WCS
    • HMS/DMS formatters
    • Haversine angular distance + DMS formatter

  • Header sanitation: SIP orders/coefficients coerced to numeric; CD/PC/CDELT types fixed; removes broken SIP where necessary to allow WCS load

  • XISF → FITS-like header: builds a WCS-capable header from XISF metadata when possible

Outputs

  • Annotated Image: JPG/PNG/TIFF (full or current view)
  • Collage: labeled grid image
  • 3D Model: interactive HTML (Plotly)
  • H–R Diagram: interactive HTML (Plotly)
  • CSV: table export
  • Plate-Solved FITS: 8/16/32-bit, mono or 3D RGB cube with combined header

Troubleshooting

  • “No WCS found / invalid”

    • Try Force Blind Solve (Settings) or use Load from View if another view already has WCS.
    • Check ASTAP path (Settings) and ensure star catalogs are installed for ASTAP.

  • Blank / clipped visualization

    • Use AutoStretch to improve display; it does not affect raw data.
    • Verify pixscale computed (Status shows radius in arcmin).

  • MAST/VizieR timeouts or empty results

    • Reduce radius, ensure search circle defined, or try again (network hiccups).

  • Orientation shows N/A

    • Missing/invalid CROTA2 and CD/PC keywords; a blind solve typically fixes this.

Extensibility Notes (for devs)

  • Document abstraction: _WIMIAdapterDoc allows the shared plate solver to write WCS back (doc.metadata).
  • Type categories: OTYPE_TO_CATEGORY, CATEGORY_TO_COLOR, and otype_long_name_lookup drive the Advanced Search tree and legend.
  • Graphics: CustomGraphicsView owns the drawing/selection state (markers, measurements, annotations) and has undo/clear/delete APIs.
  • Pluggable sources: SIMBAD/VizieR/MAST blocks are isolated—easy to add parameters or additional catalogs.
  • Headers: _sanitize_wcs_header and construct_fits_header_from_xisf centralize FITS/WCS hygiene.

Security & Privacy

  • External requests (SIMBAD/VizieR/MAST/Astrometry.net) send ROI and optional image files (Astrometry.net path).
  • Temporary FITS/TIFF files are created for solving; they’re cleaned up where possible.
  • “Publicly visible” flag on Astrometry.net uploads is set as configured in the upload call—adjust if needed.

Appendix: Controls & Signals (selected)

  • CustomSpinBox / CustomDoubleSpinBox: emit valueChanged(int/float); ▲/▼ increment by step; validator-clamped range.
  • Results selection: table single-click → select_object() in CustomGraphicsView; double-click → external URL.
  • Visibility filter: filter_visible_objects() uses OpenCV median/stddev thresholding over local pixel neighborhoods.
  • Settings: update_settings(max_results, marker_style, dialog) updates UI and redraws markers.