Skip to content

MAPBUILDER_QUICKSTART.md

Latest commit

 

History

History
352 lines (260 loc) · 6.17 KB

MAPBUILDER_QUICKSTART.md

File metadata and controls

352 lines (260 loc) · 6.17 KB

Mapbuilder Quick Start Guide

🚀 Test Mapbuilder in 15 Minutes

Step 1: Install Dependencies (5 min)

# Navigate to mapbuilder
cd D:\GitHub\mapbuilder

# Install Poetry (Python package manager)
pip install poetry --break-system-packages

# Install mapbuilder dependencies
poetry install

# Verify installation
poetry run mapbuilder --help

Expected output:

usage: mapbuilder [options] target_dir
...

Step 2: Create a Test Project (2 min)

# Create test directory
mkdir D:\GitHub\mapbuilder-test
cd D:\GitHub\mapbuilder-test

# Create structure
mkdir mapdata
mkdir output

Step 3: Create Simple Configuration (3 min)

Create D:\GitHub\mapbuilder-test\mapdata\mapbuilder.toml:

# Simple test configuration

[data.test_text]
type = "raw"
source = "test_data.txt"

[runways.CYHZ]
"05" = { heading = 51, lat = 44.8758, lon = -63.5086 }
"14" = { heading = 141, lat = 44.8847, lon = -63.4997 }
"23" = { heading = 231, lat = 44.8942, lon = -63.5244 }
"32" = { heading = 321, lat = 44.8853, lon = -63.5333 }

Step 4: Create Test Data (1 min)

Create D:\GitHub\mapbuilder-test\mapdata\test_data.txt:

This is test data for mapbuilder.
It will be included in the output.

Step 5: Create Template (2 min)

Create D:\GitHub\mapbuilder-test\mapdata\TestOutput.txt.jinja:

; Generated by Mapbuilder
; Date: {{ now }}

; Test Data
{{ data.test_text }}

; CYHZ Runways
{% for rwy_id, rwy_data in runways.CYHZ.items() %}
; Runway {{ rwy_id }}: Heading {{ rwy_data.heading }}°
;   Location: {{ rwy_data.lat }}, {{ rwy_data.lon }}
{% endfor %}

; End of test file

Step 6: Run Mapbuilder (1 min)

cd D:\GitHub\mapbuilder

poetry run mapbuilder D:\GitHub\mapbuilder-test\output -s D:\GitHub\mapbuilder-test\mapdata

Expected output:

INFO Building...
INFO Done!

Step 7: Check Output (1 min)

type D:\GitHub\mapbuilder-test\output\TestOutput.txt

You should see:

; Generated by Mapbuilder
; Date: 2024-11-30 ...

; Test Data
This is test data for mapbuilder.
It will be included in the output.

; CYHZ Runways
; Runway 05: Heading 51°
;   Location: 44.8758, -63.5086

; Runway 14: Heading 141°
;   Location: 44.8847, -63.4997

; Runway 23: Heading 231°
;   Location: 44.8942, -63.5244

; Runway 32: Heading 321°
;   Location: 44.8853, -63.5333

; End of test file

✅ Success!

If you see the output above, mapbuilder is working!

🎯 Next Test: Use Your Sector File

Step 8: Reference Your CZQQ Sector File

Update mapdata/mapbuilder.toml:

[data.czqm_runways]
type = "sct"
source = "D:/GitHub/CZQM-vACC/dev/TestSectorFiles/CZQQ.sct"  # Adjust path

[runways.CYHZ]
"05" = { heading = 51 }
"14" = { heading = 141 }
"23" = { heading = 231 }
"32" = { heading = 321 }

Create mapdata/RunwayTest.txt.jinja:

; CZQM Runways from Sector File
; Generated {{ now }}

{% for airport, rwys in data.czqm_runways.RUNWAY.items() %}
; Airport: {{ airport }}
{% for rwy in rwys %}
;   Runway {{ rwy.id }}: {{ rwy.heading }}° - {{ rwy.lat }}, {{ rwy.lon }}
{% endfor %}

{% endfor %}

Run:

poetry run mapbuilder D:\GitHub\mapbuilder-test\output -s D:\GitHub\mapbuilder-test\mapdata

Check:

type D:\GitHub\mapbuilder-test\output\RunwayTest.txt

🎓 What You Learned

  1. ✅ How to install mapbuilder
  2. ✅ How to create configuration files
  3. ✅ How to use Jinja2 templates
  4. ✅ How to run the tool
  5. ✅ How to reference your sector files

🔍 Understanding the Template Syntax

Variables

{{ variable }}              {# Output a variable #}
{{ data.source_name }}      {# Access data source #}
{{ runways.CYHZ }}          {# Access configuration #}

Loops

{% for item in list %}
  {{ item }}
{% endfor %}

Conditionals

{% if condition %}
  True branch
{% else %}
  False branch
{% endif %}

Comments

{# This is a comment #}

📚 Next Steps

Explore More Features

  1. Try GeoJSON data:

    • Create simple polygon
    • Render as TopSky COORD lines

  2. Parse ESE files:

    • Load SID/STAR procedures
    • Generate procedure definitions

  3. Use geometry functions:

    • Simplify complex shapes
    • Combine polygons
    • Buffer zones

Real-World Example

Create Class G airspace from GeoJSON:

mapdata/class_g.geojson:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "CLASS_G_TEST" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-63.5, 44.5],
          [-63.0, 44.5],
          [-63.0, 45.0],
          [-63.5, 45.0],
          [-63.5, 44.5]
        ]]
      }
    }
  ]
}

mapdata/mapbuilder.toml:

[data.class_g]
type = "geojson"
source = "class_g.geojson"

mapdata/ClassG.txt.jinja:

; Class G Airspace
{% for feature in data.class_g %}
COORD:{{ feature.properties.name }}
{% for coord in feature.geometry.coordinates[0] %}
  {{ coord[1] }}:{{ coord[0] }}
{% endfor %}
{% endfor %}

🆘 Troubleshooting

Error: "No mapbuilder.toml found"

  • Check that mapbuilder.toml is in the source directory
  • Verify path with -s flag

Error: "Module not found"

  • Run poetry install again
  • Make sure you're using poetry run

Output is empty

  • Check template syntax
  • Verify data sources are loading
  • Use --debug flag for more info: 
    poetry run mapbuilder D:\output -s D:\mapdata --debug

Template errors

  • Check Jinja2 syntax
  • Verify variable names match config
  • Test with simpler template first

📝 Summary

In 15 minutes, you:

  1. ✅ Installed mapbuilder
  2. ✅ Created a test project
  3. ✅ Wrote a template
  4. ✅ Generated output
  5. ✅ Understand the workflow

Now you can:

  • Experiment with real CZQM data
  • Create TopSky map sections
  • Automate repetitive tasks
  • Integrate with your workflow

🎯 Your Turn!

Try generating a real TopSky map section:

  • Pick one simple feature (e.g., one sector boundary)
  • Create GeoJSON or parse from sector file
  • Write template in TopSky format
  • Compare with your manual version

Good luck! 🚀