OpenWind-AU

OpenWind-AU is an open-source Python/FastAPI application for interactive preliminary wind assessment of Australian building sites. It combines terrain-category evidence, directional AS/NZS 1170.2 wind-speed calculations, obstruction inventory, and topographic analysis into a reviewable engineer-facing workflow with HTML/PDF reporting and an MCP API.

Maturity warning: OpenWind-AU is a pre-alpha engineering support tool. It does not produce certified design values.

Current maturity: pre-alpha. The project provides an interactive wind assessment workflow with directional AS/NZS 1170.2 calculations, terrain-category evidence, and MCP API tools, but is not a certified design tool. Suitable for exploration, review, contribution, and regression testing.

Who It Is For

• Structural and facade engineers reviewing terrain context.
• Wind engineering researchers and tool builders.
• Building consultants preparing early site-screening information.
• Open-source contributors interested in geospatial engineering workflows.

What It Does

• Accepts either an Australian street address or latitude/longitude, with an optional non-geocoded site_label for map-selected coordinates.
• Keeps the Design building's position, breadth/depth, and full-circle front-face engineering azimuth synchronized between the map, form, saved project state, and assessment request.
• Generates 8-direction terrain profiles: N, NE, E, SE, S, SW, W, and NW.
• Supports analysis radii of 500 m, 1000 m, 2000 m, and 4000 m.
• Performs conservative rule-based screening for candidate ridge, hill, escarpment, valley, or no significant feature outcomes.
• Provides a qualitative validation framework for representative Australian terrain examples.
• Builds a nearby obstruction inventory for shielding input review, including footprint, distance, bearing, height source, confidence, and missing-height flags.
• Uses Microsoft Australia Building Footprints as the preferred building footprint source when a local cache is configured, with OSM/Overpass used as fallback and for height/levels attributes.
• Enriches obstruction heights from DSM-DTM elevation differences when configured DSM and DTM datasets are available.
• Tracks height provenance and confidence from manual verified, DSM-DTM, OSM explicit height, OSM levels, low-confidence class assumptions, or unknown sources.
• Includes vegetation polygons as context, but excludes them from calculated shielding in accordance with AS/NZS 1170.2:2021 Clause 4.3.
• Uses a separate obstruction inventory radius so terrain/profile sampling can extend farther than the building footprint dataset used for shielding review.
• Provides preliminary shielding sector analysis from reviewed obstruction data.
• Calculates preliminary directional Mt values from DEM-derived topographic geometry using AS/NZS 1170.2:2021 Clause 4.4 equations, including Australian A0 and A4 adjustments.
• Generates directional terrain category evidence for engineer review, including built-up, vegetation, open-terrain, obstruction density, height, confidence, and suggested range evidence.
• Calculates Clause 4.2.3 distance-weighted Mz,cat for supplied complete, ordered, source-referenced non-A0 terrain-transition profiles. Region A0 keeps its mandatory terrain-independent value and treats supplied profiles as evidence only; aggregate GIS sector evidence does not infer transition distances.
• Exports JSON, HTML, and PDF reports.
• Provides qualitative validation checks against representative Australian terrain examples.
• Exposes traceable VR, Mc, Md, Mz,cat, Ms, Mt, Vsit,b, and Clause 2.3 building-orthogonal Vdes,theta tools through an MCP server.

What It Does Not Do

OpenWind-AU does not produce:

• certified topographic multipliers without review of the DEM-derived feature geometry;
• final terrain category assignments;
• automatic terrain-transition detection from aggregate built-up, vegetation, or open-terrain sector percentages;
• design wind pressures;
• AS 4055 wind classifications;
• certified shielding multiplier Ms;
• certified design compliance.

Outputs are preliminary and must be reviewed by a competent engineer. Public DEM data may not reflect local survey levels, recent earthworks, retaining structures, vegetation, or built obstructions.

The obstruction inventory uses Microsoft Australia Building Footprints as the preferred source when cached regional data is available. OSM/Overpass is used as a fallback and to preserve useful attributes such as height, building:levels, and building type. If Microsoft and OSM footprint sources are both unavailable, OpenWind-AU returns warnings rather than calculating indicative shielding from incomplete data.

DSM-DTM height enrichment is optional and depends on configured elevation datasets. Without a DSM and DTM, obstruction heights fall back to manual, OSM-derived, or low-confidence assumption-based sources and the response includes warnings.

Screenshots

Screenshot coverage is tracked in docs/screenshots.md:

• Terrain category evidence: docs/screenshots/terrain-category-evidence.png

• Site analysis page: docs/screenshots/site-analysis.placeholder.md

• Terrain profiles: docs/screenshots/terrain-profiles.placeholder.md

• Topographic screening: docs/screenshots/topographic-screening.placeholder.md

• Validation report: docs/screenshots/validation-report.placeholder.md

Quick Start

If you have a wheel artifact built from this exact commit, install it in a fresh virtual environment:

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install .\openwind_au-0.8.0-py3-none-any.whl
openwind-au --help
openwind-au-mcp --help
openwind-au check --json
openwind-au

openwind-au check --json intentionally reports not_ready with exit status 1 until the production datasets, signing key, and engineering review metadata are configured. That diagnostic does not mean the wheel failed to install.

For a development checkout, install from source:

git clone https://github.com/Elandu/OpenWind-AU.git
cd OpenWind-AU
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
openwind-au

On macOS or Linux, activate with:

source .venv/bin/activate

Open the interactive wind assessment workflow:

http://127.0.0.1:8000

The terrain category evidence and legacy site-analysis pages are also available at:

http://127.0.0.1:8000/site-analysis
http://127.0.0.1:8000/terrain-category

Before routing production assessment traffic, run the same readiness checks used by /health without starting a server:

openwind-au check
openwind-au check --json

The command exits with status 0 only when the deployment is ready and status 1 when any required dataset, reviewed lookup, digest, signing key, or DEM check fails. A source checkout without the project-specific production inputs is expected to report NOT_READY. Invalid command-line usage exits with status 2.

Microsoft Building Footprint Cache

Microsoft publishes Australia Building Footprints as a large country-wide GeoJSON ZIP. OpenWind-AU does not silently download the full dataset during an analysis. For local footprint coverage, prepare a clipped or tiled GeoJSON/GeoJSONL cache and set:

$env:OPENWIND_MICROSOFT_FOOTPRINT_CACHE="C:\data\openwind-au\microsoft_building_footprints"

Tile files can be placed at tiles/<lat_floor>_<lon_floor>.geojsonl or tiles/<lat_floor>_<lon_floor>.geojson, for example tiles/-34_151.geojsonl for central Sydney. Each record should be a GeoJSON Feature or Polygon in EPSG:4326. If no Microsoft cache is found, the app uses OSM/Overpass fallback where available and reports that fallback in the obstruction source diagnostics.

If a project maintains its own tile index, set OPENWIND_MICROSOFT_FOOTPRINT_INDEX or OPENWIND_MICROSOFT_FOOTPRINT_INDEX_URL. The index maps tile keys to downloadable GeoJSON or GeoJSONL URLs, allowing OpenWind-AU to fetch only the tile required for the current site. Remote index and tile URLs (including redirects) must use HTTPS. Remote indexes are limited to 2 MiB, tiles are limited to 50 MiB, and an optional per-tile sha256 is verified before a supported GeoJSON file is installed atomically in the cache.

Successful OSM fallback queries use a separate bounded outage cache. Its hashed filenames, atomic-write and retention limits, location-data privacy implications, and deletion procedure are documented in Installation.

Wind Region GIS Dataset

OpenWind-AU uses a local GIS file for wind-region lookup. The preferred source is Geoscience Australia's 1170.2 Wind Regions for Australia dataset. The catalogue data download is currently published at https://d28rz98at9flks.cloudfront.net/146359/146359_01_0.zip.

OpenWind-AU does not hard-code the map from an image and does not silently download this dataset during an assessment. Download and extract the GA data locally, then set the local GeoJSON or GPKG path:

$env:OPENWIND_WIND_REGION_DATASET="C:\data\openwind-au\1170_2_wind_regions.gpkg"

For a GeoPackage with multiple layers, set OPENWIND_WIND_REGION_LAYER. If the region attribute is not auto-detected, set OPENWIND_WIND_REGION_FIELD to the field containing labels such as A0, A1, B1, B2, C, or D. Sample polygons in this repository are test fixtures only and are not a production wind-region map.

Documentation

• Installation
• Running locally
• Workflow guide
• Calculation basis and data lineage
• Base AS/NZS 1170.2:2021 verification matrix
• Reviewer checklist
• API usage
• MCP server
• Report exports
• Validation framework
• Limitations and engineering review
• Release checklist
• Unreleased v0.8.0 milestone changes
• v0.6.0 release notes

API Overview

Run an analysis:

curl -X POST http://127.0.0.1:8000/api/analyse \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": -33.8568,
    "longitude": 151.2153,
    "building_height_m": 12,
    "radius_m": 2000,
    "sample_interval_m": 100
  }'

Main endpoints:

GET  /health/live
GET  /health
POST /api/geocode/suggest
POST /api/geocode/resolve
POST /api/analyse
POST /api/wind-workflow
POST /api/wind-workflow/stream
POST /api/wind-workflow/map
POST /api/export/json
POST /api/report/html
POST /api/report/pdf
POST /api/wind-workflow/report/html
POST /api/wind-workflow/report/pdf
POST /api/wind-workflow/result/report/html
POST /api/wind-workflow/result/report/pdf
POST /api/plots/profile
POST /api/maps/site
POST /api/map/combined
POST /api/obstructions/inventory
POST /api/obstructions/map
POST /api/obstructions/report/html
POST /api/terrain-category/evidence
POST /api/terrain-category/map
POST /api/terrain-category/report/html
POST /api/wind-region
POST /api/wind-region/map
GET  /api/terrain-category/validation
GET  /terrain-category
GET  /validation
GET  /api/validation
GET  /api/validation/report/html

/health/live is the process-liveness probe. /health is the stricter assessment-readiness probe and returns HTTP 503 with component checks until required production datasets, reviewed lookup tables (VR, Md, Mz,cat, and Ms), matching lookup digests, and the configured DEM provider/cache are usable. All four lookup assets are digest-protected: VR and Md hash their canonical tables objects, while Mz,cat and Ms hash their canonical values objects. Completed-result report endpoints also require the unmodified integrity_token returned by the workflow. Production deployments must configure the same 32-byte-or-longer OPENWIND_RESULT_SIGNING_KEY on every API worker.

Example Outputs

• Sample request
• Sample JSON analysis
• Sample HTML report
• Sample validation report
• Example workflow
• Demo project folder

Validation

The validation framework runs the normal terrain/topographic workflow against broad Australian examples: flat suburban, coastal escarpment, hilltop, valley, and inland-flat settings. Results are reported as pass, warning, or fail against broad expected behaviour.

Validation is an audit and regression tool. It does not prove design accuracy, code compliance, or fitness for a specific project.

Development

pytest
ruff check .
ruff format --check .

CI runs these checks through GitHub Actions.

Suggested GitHub Topics

open-source, wind-engineering, structural-engineering, as-nzs-1170-2, geospatial, gis, terrain-analysis, topography, python, fastapi, microsoft-building-footprints, openstreetmap

Roadmap

See ROADMAP.md. Near-term work focuses on better validation examples, clearer confidence reporting, improved public documentation, and design-certification readiness.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md, keep claims preliminary, and do not include private project data in public issues or examples.

Security

See SECURITY.md for vulnerability reporting and sensitive-data guidance.

Changelog

See CHANGELOG.md.

Licence

GNU Affero General Public License v3. See LICENSE.