Data Loading Guide:
Assets & Protection Measures

01Overview

The flood alignment pipeline accepts data through five distinct pathways, each suited to a different stage of the design workflow. Data flows from source formats into pipeline-ready GeoJSON, then into the FloodAdapt database for SFINCS hydrodynamic simulation and FIAT damage assessment.

Two categories of features can be loaded: protection measures (barriers, stormwater infrastructure, building-level adaptations) and building assets (exposure data for damage calculation).

02Loading Pathways

Rhino .3dm Files

The ingest_cad.py script reads native Rhino .3dm files using the rhino3dm Python library. This is the recommended pathway for design teams because it preserves per-object attributes set via Rhino's SetUserText command.

# Basic usage (defaults to UTM 18N source CRS)
python scripts/ingest_cad.py my_design.3dm

# Specify source CRS (e.g., NY State Plane)
python scripts/ingest_cad.py my_design.3dm --source-crs EPSG:2263

# Custom layer mapping + output directory
python scripts/ingest_cad.py my_design.3dm --layer-config layers.yaml --output-dir ./pipeline

# Dry run (preview without writing)
python scripts/ingest_cad.py my_design.3dm --dry-run

Layer names in the Rhino file are normalized to lowercase with underscores. The script maps each layer to a pipeline target directory and applies default properties (which can be overridden per-object via User Text).

DXF / DWG Files

DXF files are read using ezdxf. The same ingest_cad.py script handles DXF input with identical layer mapping. Per-object attributes are extracted from extended data (xdata) tags in key=value format.

Supported DXF entity types:

• POINT → Point geometry (pump stations, markers)
• LINE → LineString (simple barriers)
• LWPOLYLINE / POLYLINE → LineString or Polygon (if closed)
• CIRCLE → Polygon (buffered point)
• ARC → LineString (sampled along arc)
• SPLINE → LineString or Polygon (flattened)
• ELLIPSE → Polygon (flattened)
• HATCH → Polygon / MultiPolygon (from boundary paths)

Direct GeoJSON

The most direct method: create or export GeoJSON files and place them in the appropriate subdirectory. The AlignmentLibrary auto-discovers all .geojson files under protection_measures/ at runtime.

protection_measures/
├── barriers/
│   ├── frontline_seawall.geojson     # levees, gates, walls
│   └── my_custom_barrier.geojson
├── stormwater/
│   ├── pump_stations.geojson         # pumps, retention, green infra
│   └── bioswale_network.geojson
└── building/
    └── floodproofing_zone.geojson    # building-level measures

custom_buildings/
└── my_buildings.geojson              # custom building footprints

GeoJSON files must be in WGS84 (EPSG:4326). The pipeline handles reprojection to the study area CRS internally. See the GeoJSON schema section for required properties.

HATS WFS Source

The fetch_hats_alignments.py script downloads published flood protection alignments from NYC's HATS (Harbor and Tributaries Study) ArcGIS WFS service. These are city-engineered alignment scenarios with defined crest elevations and feature types.

Key HATS features loaded:

• Seawalls — continuous shoreline barriers
• Floodwalls (large / medium) — inland flood barriers
• Levees (large / small) — earthen embankments
• Deployable flood barriers — vehicle gates, pedestrian gates

YAML Configuration

Measures can be declared in the study area config file under protection_alignments. This supports referencing preset geometries, external GeoJSON files, or GeoPackage files.

protection_alignments:
  - name: "harlem_river_frontline"
    measures:
      # Reference a preset geometry generator
      - type: "levee"
        geometry: "auto:harlem_frontline"
        crest_elevation_m: 5.33

      # Reference an external GeoJSON file
      - type: "levee"
        geometry: "my_barrier.geojson"
        crest_elevation_m: 4.5
        width_m: 2.0

      # Green infrastructure preset
      - type: "green_infra"
        geometry: "auto:university_ave_corridor"

      # Building-level measures (no geometry needed)
      - type: "elevate_properties"
        elevation_increase_ft: 2.0
        selection_type: "all"

Available Preset Geometries

03Protection Measure Types

The pipeline supports three categories of protection measures: barrier (spatial flood barriers), stormwater (drainage infrastructure), and building-level (per-property adaptations). Each has a distinct geometry type and required properties.

Barrier Measures (Spatial)

Barrier measures are LineString geometries that modify the SFINCS model terrain. During simulation, levee crest elevations are rasterized onto the DEM grid, blocking water flow across the barrier alignment.

Barrier Properties Reference

Stormwater Measures

Stormwater Properties Reference

Building-Level Measures

These measures modify the damage calculation rather than the hydrodynamic model. They don't require spatial geometry and are applied to buildings matching a selection criteria. Defined via YAML config or the building_prot layer in Rhino.

04Building Assets

Automatic: NYC Open Data Pipeline

The DataProcessor in preprocessing.py automatically downloads and enriches building data from NYC Open Data. This is the default for any study area within NYC.

The pipeline performs these enrichment steps:

1. Downloads footprints from the 5zhs-2jue dataset (WGS84)
2. Joins with PLUTO tax-lot data by BBL to get assessed values and land use codes
3. Maps NYC building class codes to standardized use categories
4. Computes first-floor elevation (FFE) by use category

Default First-Floor Heights

Custom Buildings (from Rhino or GeoJSON)

For buildings not in the NYC database (proposed developments, hypothetical scenarios), place GeoJSON files in custom_buildings/ or use the buildings layer in a Rhino file.

Custom Building Properties

Custom buildings should have Polygon geometry (closed curves in Rhino). The damage model samples flood depth at the polygon centroid and applies HAZUS depth-damage curves based on the use_category.

05GeoJSON Schemas

All GeoJSON files in the pipeline use the same FeatureCollection wrapper with additional metadata fields at the collection level.

{
  "type": "FeatureCollection",
  "name": "frontline_seawall",          // machine identifier
  "label": "Frontline Seawall",         // display name
  "description": "Seawall along...",      // optional description
  "category": "barriers",               // barriers | stormwater | building
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [[-73.935, 40.836], [-73.934, 40.839]]
      },
      "properties": {
        "measure_type": "levee",
        "measure_name": "East Harlem — Seawall",
        "crest_elevation_m": 5.33,
        "width_m": 2.5
      }
    }
  ]
}

{
  "type": "FeatureCollection",
  "name": "proposed_development",
  "label": "Proposed Development",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[-73.914, 40.862], ...]]
      },
      "properties": {
        "use_category": "multi_family",
        "height_m": 15.5,
        "replacement_value_usd": 500000,
        "first_floor_height_m": 0.46
      }
    }
  ]
}

06Rhino Layer Setup

Layer Name → Pipeline Target Mapping

Name your Rhino layers using these conventions. Layer names are case-insensitive and spaces are converted to underscores. Any unmapped layer is skipped with a warning.

Default Properties per Layer

Each layer has defaults that apply unless overridden by Rhino User Text on individual objects:

Per-Object Attributes via User Text

In Rhino, select an object and use SetUserText to attach key-value pairs. These override layer defaults for that specific object.

// Select a barrier curve, then:
SetUserText crest_elevation_m 5.33
SetUserText width_m 2.5
SetUserText measure_name "East Harlem Seawall Section A"

// For a building polygon:
SetUserText use_category multi_family
SetUserText replacement_value_usd 1200000
SetUserText first_floor_height_m 0.46

// For a pump station point:
SetUserText capacity_cms 12.5
SetUserText measure_name "West 225th St Pump"

Rhino Geometry → GeoJSON Conversion

07Coordinate Reference Systems

The pipeline uses a two-CRS workflow: GeoJSON storage in WGS84 and analysis in a projected CRS.

Override the source CRS for Rhino/DXF files with --source-crs. Common alternatives for NYC:

• EPSG:2263 — NY State Plane Long Island (US feet)
• EPSG:6539 — NY State Plane Long Island (metres, NAD83 2011)
• EPSG:32618 — UTM Zone 18N (metres) — default

Vertical Datum

All elevations are in NAVD88 (metres). The pipeline defines offsets for other datums:

08FloodAdapt Database

All loaded data ultimately feeds into the FloodAdapt database, which orchestrates SFINCS flood simulations and FIAT damage assessments. The database is built by build_floodadapt_db.py using the DatabaseBuilder API.

floodadapt_db/university_heights/
├── static/
│   ├── templates/
│   │   └── overland/              # SFINCS model template
│   ├── config/
│   │   └── site.toml              # Site configuration
│   └── fiat/
│       └── geoms/                 # Building footprints (exposure)
├── input/
│   ├── events/                    # Flood scenarios (storm params)
│   └── measures/                  # Protection measures
│       └── fw_Inwood___Large_Levee/
│           └── fw_*.geojson       # Measure geometry in WGS84
└── output/
    └── scenarios/                 # Simulation results
        └── fa_10yr_surge/
            ├── Flooding/
            │   └── max_water_level_map.tif
            └── Impacts/
                └── fiat_model/
                    └── results.gpkg

Protection measures placed in protection_measures/ are automatically discovered by the AlignmentLibrary, which builds scenario combinations and registers them with FloodAdapt. The database supports running any combination of:

• Events — 10yr, 25yr, 50yr, 100yr, 500yr storm surges with optional rainfall
• Climate scenarios — current, 2050, 2080, 2100 sea-level rise adjustments
• Protection scenarios — no protection (baseline), individual measures, or comprehensive (all combined)

09Format Comparison