Skip to content

user-guide.md

Latest commit

 

History

History
227 lines (165 loc) · 8.46 KB

user-guide.md

File metadata and controls

227 lines (165 loc) · 8.46 KB

azMap User Guide

Installation

Dependencies

  • GLFW 3 - windowing and input
  • GLEW - OpenGL extension loading
  • shapelib - shapefile parsing
  • libcurl - HTTP requests (QRZ callsign lookup)
  • OpenGL 3.3+ - rendering

Arch / Manjaro

sudo pacman -S glfw shapelib glew curl

Ubuntu / Debian

sudo apt install libglfw3-dev libglew-dev libshp-dev libcurl4-openssl-dev

Building

mkdir -p build && cd build
cmake ..
make

The binary is placed at build/azmap. Shaders are copied to build/shaders/ automatically.

Installing (optional)

sudo cmake --install build

This installs:

  • azmap binary to <prefix>/bin/
  • Shaders to <prefix>/share/azmap/shaders/
  • Map data (if present) to <prefix>/share/azmap/data/

The executable automatically detects whether it's running from the build tree or an installed location and resolves data/shader paths accordingly.

Map Data

azMap uses Natural Earth 110m shapefiles. Download and extract them so the directory structure looks like:

data/
  ne_110m_coastline/
    ne_110m_coastline.shp
    ne_110m_coastline.shx
    ne_110m_coastline.dbf
  ne_110m_land/                          (optional — filled land masses)
    ne_110m_land.shp
    ...
  ne_110m_admin_0_boundary_lines_land/   (optional — country borders)
    ne_110m_admin_0_boundary_lines_land.shp
    ...

Coastlines are required. Land polygons and country borders are optional and will be silently skipped if not found.

Config File

You can set a default center location (your QTH) in ~/.config/azmap.conf so you only need to specify the target on the command line:

# azMap configuration
name = Madrid
lat = 40.4168
lon = -3.7038

# QRZ.com credentials (optional, for callsign lookup)
qrz_user = YOURCALL
qrz_pass = yourpassword
  • Lines starting with # are comments
  • Whitespace around = is ignored
  • lat and lon must both be present to be used; name is optional
  • qrz_user and qrz_pass enable the QRZ callsign lookup feature
  • CLI arguments always override config values

Usage

./azmap <center_lat> <center_lon> <target_lat> <target_lon> [options]
./azmap <target_lat> <target_lon> [options]   # center from config

Positional Arguments

Argument Description
center_lat Latitude of projection center (degrees, -90 to 90)
center_lon Longitude of projection center (degrees, -180 to 180)
target_lat Latitude of target location
target_lon Longitude of target location

When a valid config file provides the center location, only target_lat and target_lon are required.

Options

Flag Description
-c NAME Display name for the center location (overrides config name)
-t NAME Display name for the target location
-d DETAIL Station detail string for sidebar display (station|freq|country|site|lang|target)
-s PATH Override the default coastline shapefile path

For backward compatibility, a bare fifth positional argument is also accepted as the shapefile path.

Examples

# Madrid to Paris, with names
./azmap 40.4168 -3.7038 48.8566 2.3522 -c Madrid -t Paris

# With config file providing center — just pass the target
./azmap 48.8566 2.3522 -t Paris

# Tokyo to New York
./azmap 35.6762 139.6503 40.7128 -74.0060 -c Tokyo -t "New York"

# Custom shapefile
./azmap 51.5074 -0.1278 -33.8688 151.2093 -s /path/to/my.shp

On-Screen Display

Projection Modes

azMap supports two projection modes, toggled by the Proj button in the toolbar:

  • Azimuthal equidistant (default) — the entire Earth is shown. Distances from the center are true to scale. The grid shows concentric range rings (every 5000 km) and radial azimuth lines (every 30 degrees).
  • Orthographic — one hemisphere is shown as if viewed from space. Back-hemisphere geometry is clipped at the horizon. The grid shows geographic parallels (every 30 degrees, -60 to 60) and meridians (every 30 degrees).

All other features (day/night overlay, markers, labels, pan, zoom) work in both modes. The zoom range adapts to the projection radius.

Map Elements

  • Dark blue circle - Earth boundary
  • Filled land - Medium gray land masses (if ne_110m_land data available)
  • Dim grid - Range rings + radials (azimuthal equidistant) or parallels + meridians (orthographic)
  • Gray lines - Country borders (if data available)
  • Dark gray lines - Coastlines
  • Yellow line - Great-circle path from center to target (curved arc in orthographic mode)
  • White filled circle - Center location marker
  • Red outline circle - Target location marker
  • White triangle - North pole indicator
  • Dark overlay - Night side of the Earth with smooth twilight gradient (updates every 60 seconds from system UTC time)

Text Overlays

  • Top-center HUD (white) - Distance in km, azimuth to/from target, local and UTC clocks (updated every second)
  • Center label (cyan) - Center location name and coordinates
  • Target label (orange) - Target location name and coordinates

If no -c or -t name is given, labels show coordinates only (e.g., 40.42N, 3.70W).

Sidebar Panel

The sidebar is always visible on the right side of the window. It displays:

  • UTC and local clocks at the top
  • Station info (from swl dashboard or QRZ lookup) in the middle
  • Distance and azimuth readouts (shown only when a target is active)
  • LAYERS section — Aurora, Spor.E, MUF overlay toggle buttons
  • MUF legend — when the MUF layer is active, a color-coded legend of contour MHz values appears above the LAYERS label
  • Kp/Bz indices — when Aurora is active, geomagnetic Kp index and IMF Bz component are displayed right-aligned in the sidebar
  • SOURCE section — QRZ, WSJT, BCB buttons

Section labels and horizontal divider lines separate the button groups.

QRZ Lookup

The QRZ button opens a popup panel for looking up amateur radio callsigns. Type a callsign and press Enter to query the QRZ.com XML API. On success, the popup closes and results (call, name, location, grid, coordinates) display in the sidebar. The target marker, line, and distance/azimuth update automatically.

  • The popup can be dragged by its title bar
  • Press Esc or the X button to close
  • QRZ credentials (qrz_user and qrz_pass) must be set in ~/.config/azmap.conf

Layer Buttons

  • Aurora — Toggles the live aurora probability heatmap overlay (green, semi-transparent). Data is fetched from the NOAA OVATION Aurora service (services.swpc.noaa.gov) and auto-refreshes every 15 minutes while active. The overlay shows aurora probability as a green heatmap with per-vertex alpha: probabilities below 5% are transparent, 5–50% ramp to half opacity, and 50–100% reach maximum opacity. When active, also fetches and displays Kp index and Bz component from NOAA SWPC in the sidebar.
  • MUF — Toggles live Maximum Usable Frequency contour lines. Data is fetched from KC2G (prop.kc2g.com) as GeoJSON and auto-refreshes every 15 minutes while active. Each contour is drawn in its own color corresponding to the HF band frequency. When active, a color-coded legend showing the MHz values appears above the LAYERS label in the sidebar.
  • Spor.E — Sporadic E layer toggle (planned).

Source Buttons

  • QRZ — Opens callsign lookup popup. Clears previous station info and target.
  • WSJT — Opens WSJT popup (placeholder). Clears previous info.
  • BCB — Clears station info, target line, marker, label, and distance/azimuth.

Controls

Input Action
Scroll wheel Zoom in/out (range: 10 km to full Earth)
Left mouse drag Pan the map
Arrow keys Pan the map
Proj button Toggle azimuthal equidistant / orthographic projection
Aurora button Toggle live aurora probability heatmap overlay
MUF button Toggle live MUF contour lines overlay with sidebar legend
QRZ button Open callsign lookup popup (clears previous info)
WSJT button Open WSJT popup (clears previous info)
BCB button Clear station info, target, and distance/azimuth
Drag popup title bar Reposition the popup window
R Reset view (full Earth, centered)
Q / Esc (or Esc in popup) Quit (or close popup)

Console Output

On startup, azMap prints summary info to the terminal:

Center:   40.4168, -3.7038
Target:   48.8566, 2.3522
Distance: 1053.4 km
Az to:    28.7 deg
Az from:  209.5 deg