CAsMan

Grid Position Coordinates

This document describes how to manage geographic coordinates (latitude, longitude, height) for antenna grid positions.

Overview

The parts.db database includes coordinate data in two places:

• grid_positions for all grid locations (independent of antenna assignments)
• antenna_positions for assigned antennas (optional coordinates)

The antenna_positions table includes optional coordinate columns:

• latitude (REAL): Latitude in decimal degrees
• longitude (REAL): Longitude in decimal degrees
• height (REAL): Height in meters above reference
• coordinate_system (TEXT): Coordinate system identifier (e.g., ‘WGS84’, ‘local’)

Coordinates are managed via CSV file (database/grid_positions.csv) for easy editing and version control.

CSV Format

The CSV file has the following columns:

grid_code,latitude,longitude,height,coordinate_system,notes
CN021E01,37.8719,-122.2585,10.5,WGS84,North row 21 east 1
CN021E02,37.8720,-122.2583,10.6,WGS84,North row 21 east 2

• grid_code: Grid position identifier (e.g., ‘CN021E01’) - Note: uses 1-based indexing for east columns
• latitude: Decimal degrees (e.g., 37.8719)
• longitude: Decimal degrees (e.g., -122.2585)
• height: Height in meters (e.g., 10.5)
• coordinate_system: System identifier (e.g., ‘WGS84’, ‘local’)
• notes: Optional description

Empty coordinate values are skipped during loading.

Usage

1. Edit Coordinates

Edit database/grid_positions.csv in a text editor or spreadsheet application:

# With text editor
nano database/grid_positions.csv

# Or import to spreadsheet (Excel, Google Sheets, LibreOffice Calc)
# Then export as CSV when done

Template: A template with all 258 core array positions (CN021E01 through CS021E06) is provided in database/grid_positions.csv. Note that the core array uses 1-based indexing for east columns (E01-E06).

2. Load Coordinates

After editing the CSV, load coordinates into the database:

# Load from default CSV (database/grid_positions.csv)
casman database load-coordinates

# Load from custom CSV
casman database load-coordinates --csv my_survey.csv

The command will report:

• Number of positions loaded/updated
• Number of positions skipped
• Any errors encountered

Example output:

Loading grid coordinates from CSV...
==================================================

Updated: 3 position(s)
  Skipped: 0 position(s)

Coordinate data loaded successfully

3. Verify Coordinates

Query the database to verify coordinates were loaded:

sqlite3 database/parts.db "SELECT grid_code, latitude, longitude, height FROM grid_positions WHERE latitude IS NOT NULL;"

Workflow

1. Field Survey: Measure coordinates with GPS equipment or total station
2. Data Entry: Enter coordinates into database/grid_positions.csv
3. Version Control: Commit CSV changes with git commit
4. Load: Run casman database load-coordinates to update grid_positions
5. Deploy: Updated coordinates are now available in the application

Important Notes

• Updates/Inserts: The loader updates existing grid positions and inserts new ones into grid_positions.
• Independent of Assignments: Loading coordinates does not require antennas to be assigned.
• Overwrites Data: Loading coordinates will overwrite existing coordinate values for that grid position.
• CSV-Based: No web UI for coordinate entry - all changes happen via CSV file editing.
• Version Controlled: CSV file should be committed to git for change tracking.

Example: Adding Coordinates

1. Assign an antenna to a position (if not already assigned):

   # Via scanner web interface at http://localhost:<dev-port>/scanner
   # Scan antenna ANT00001 and assign to CN021E01
   

2. Add coordinates to CSV:

   grid_code,latitude,longitude,height,coordinate_system,notes
   CN021E01,37.871899,-122.258477,10.5,WGS84,North row 21 east 1
   

3. Load coordinates:

   casman database load-coordinates
   

4. Verify:

   sqlite3 database/parts.db "SELECT * FROM grid_positions WHERE grid_code='CN021E01';"
   

Coordinate Systems

Common coordinate system identifiers:

• WGS84: World Geodetic System 1984 (GPS standard)
• NAD83: North American Datum 1983
• local: Local survey coordinates (relative to site reference)
• ITRF: International Terrestrial Reference Frame

Choose a coordinate system appropriate for your site and measurement equipment.

API Access

Coordinates are automatically included in position queries:

from casman.database.antenna_positions import get_antenna_position

pos = get_antenna_position('ANT00001')
if pos:
    print(f"Latitude: {pos.get('latitude')}")
    print(f"Longitude: {pos.get('longitude')}")
    print(f"Height: {pos.get('height')}")
    print(f"System: {pos.get('coordinate_system')}")

If you need to update coordinates on antenna assignments directly, use load_grid_coordinates_from_csv() from the antenna_positions module.

Troubleshooting

No positions updated:

• Verify CSV has valid coordinate data (not empty)
• Check grid_code values match database records
• Ensure antennas are assigned to grid positions first

CSV file not found:

• Default path is database/grid_positions.csv
• Use --csv flag to specify different file
• Check working directory is project root

Coordinate values incorrect:

• Verify decimal degrees format (not degrees/minutes/seconds)
• Check sign convention (North/East positive, South/West negative)
• Ensure height units are meters