Contour Plotter

1. User Guide

Contour Plotter is an offline web application for creating contour maps from CSV survey data. It supports optional background images or CAD drawings, cross-section elevation profiles, and export to PNG, DXF, and project JSON.

Getting started

CSV data format

• Minimum 3 valid rows across enabled files.
• Header names are case-insensitive. Delimiter auto-detected (comma, semicolon, tab).
• Decimals: . or ,. Negative X, Y, Z supported. Large UTM coordinates supported.
• Multiple CSV files: enable/disable individually in the file list.

X,Y,Z
100.000,200.000,12.400
101.500,201.200,13.100
102.000,199.800,11.900

Workflow

1. Upload CSV — sidebar Data → drag or select one or more .csv files. Plot auto-generates on success.
2. Adjust Contour settings (interval, colors, theme) as needed.
3. Use Fit to Data (bottom-right) to reset the view.
4. Export PNG, DXF, or project JSON from the sidebar.

After changing Grid resolution or Clip to data hull, click Generate Plot to re-run interpolation.

Background overlays

Image (JPG / PNG)

1. Set background to IMAGE.
2. Upload image; optionally drop a world file (.jgw, .pgw, .tfw) together.
3. Set extent fields (X-min, X-max, Y-min, Y-max) or click Auto from CSV.
4. Use 2-point calibration to align by clicking two known locations and entering world coordinates.
5. Import inverted… inverts colors (light plans → dark background for dark theme).

DXF (CAD)

1. Set background to DXF and upload .dxf (max 150 MB).
2. Lines appear under the contour; view auto-fits to combined bounds.

Cross section profiles

1. Generate a contour plot from CSV data.
2. Enable Cross section in the sidebar.
3. Set Start angle (0° = East, 90° = North) and optional Section line length.
4. Click Add section line — line appears at map centre.
5. Drag endpoints on the map. Add more lines (A, B, C, …) for comparison.
6. Export CSV with Export cross section CSV (set export interval first).

CSV export format (wide): Distance,Elevation A,Elevation B,… — one row per distance step. Blank cells where the sample falls outside the interpolated area (e.g. hull clipping).

Project save and load

Export project / Import project saves a .json file containing all CSV datasets, contour settings, backgrounds, viewport, and cross-section state.

Plot viewer

Axis labels use 3 decimal places. Map keeps 1:1 scale (1 m in X = 1 m in Y on screen).

Troubleshooting

2. Geography & Topography Fundamentals

Contour Plotter draws on classical topographic cartography. Understanding how contour lines represent land surface helps you choose interval, read the map, and validate exports against field survey.

What contour lines are

A contour line (contour) is a line on a map joining points of equal elevation above a chosen datum (e.g. mean sea level, local benchmark, or project zero). On a topographic map, every point along one contour has the same height; moving across a contour means changing elevation.

In this application, the Z column in your CSV is treated as that scalar value—most often elevation (m or ft), but it can represent any continuous field (e.g. groundwater head, pollution concentration) that you wish to visualize as isolines.

Reading slope and landform from contours

• Contour spacing: Lines close together indicate steep slope; widely spaced lines indicate gentle slope. The horizontal distance between lines at a given interval is inversely related to gradient.
• Valleys and ridges: Contours form V shapes where they cross valleys or ridges. The V points upstream (toward higher ground) in a valley; on a ridge, bends point toward lower ground.
• Hills and depressions: Closed loops indicate hills (higher values toward the centre) or depressions/basins (lower values toward the centre). Without hatch marks, compare inner labels to outer labels to distinguish mound vs hollow.
• Uniform slope: Parallel, evenly spaced contours suggest a planar or uniform gradient (cut slope, embankment, or flat terrace).

Survey coordinates and elevation (Z)

Topographic surveys typically record:

• X, Y — horizontal position on a projected coordinate system (e.g. UTM easting/northing) or local site grid.
• Z — height from GNSS, total station, or level run.

Discrete survey points are rarely dense enough to draw smooth contours directly. Cartographers and GIS software interpolate a surface between points, then extract contours at regular Z intervals—the same workflow this tool uses (grid → interpolate → contour levels).

Cross sections in civil and geotechnical work are vertical slices along a plan line (chainage vs elevation). The app’s cross-section export samples the interpolated surface along user-drawn lines—analogous to a section cut on a topographic model.

How this tool relates to published topographic maps

Always treat interpolated contours between survey points as modelled, not measured. Increase point density or reduce grid spacing where detail matters; use hull clipping to avoid drawing contours in unsampled voids.

3. Mathematics & Algorithms

This section describes how survey points become a displayed contour map. The pipeline runs entirely in the browser.

Processing pipeline

1. Parse CSV → array of (X, Y, Z) points; compute data statistics (bounds, Z min/max).
2. Build interpolation grid → regular N×N lattice over the XY bounding box.
3. Interpolate Z at each grid node (Delaunay + barycentric, with IDW fallback).
4. Optional hull clip → set grid cells outside the convex hull to NaN.
5. Render → Plotly contour trace on the grid; contour levels from step size.
6. DXF export → separate pass using d3-contour marching squares on the same grid.

Grid construction & interpolation

The Grid resolution parameter sets both row and column count (50–300, default 100). The grid spans the axis-aligned bounding box of all survey points:

Coordinates are shifted by an origin (x₀, y₀) near the data centroid before interpolation to improve floating-point precision for large survey coordinates (e.g. UTM).

Primary method: Delaunay triangulation + barycentric interpolation

For each grid node (px, py):

1. Build a Delaunay triangulation of all survey points in local coordinates.
2. Find the triangle containing (px, py) by testing barycentric weights w_A, w_B, w_C ≥ 0.
3. Interpolate: Z = w_A·Z_A + w_B·Z_B + w_C·Z_C.

Barycentric weights for point P in triangle ABC:

Higher grid resolution → finer lattice → smoother contours and more detail between points, at the cost of computation time.

IDW fallback (Inverse Distance Weighting)

When Delaunay fails or a grid node lies outside all triangles, the tool falls back to IDW with power p = 2:

If the grid node coincides exactly with a survey point (d = 0), that point's Z value is used directly. IDW produces smooth blending but can create bull's-eye patterns near isolated points; the Delaunay path is preferred inside the triangulated region.

Convex hull clipping

When Clip contours to data area is enabled:

1. Compute the convex hull of all survey XY positions (Andrew's monotone chain algorithm).
2. For each grid cell centre, test point-in-polygon (ray casting).
3. Cells outside the hull → Z set to NaN.

Plotly is configured with connectgaps: false, so NaN cells break both filled regions and contour lines at the hull boundary. This prevents extrapolation into areas with no survey coverage. Disabling hull clip leaves the full rectangular grid interpolated (including extrapolated corners).

Contour level generation

Contour levels are not auto-generated (autocontour: false). They are computed from the contour interval (step) and the data Z range:

Levels are placed at start, start + step, start + 2·step, … up to end. This grid alignment ensures negative Z values are fully covered and labels align to round values.

The on-screen contour trace sets zmin/zmax to the data range and contours.size to the step. Labels show 3 decimal places (labelformat: '.3f').

For DXF export, d3-contour marching squares extracts iso-lines at the same threshold levels from the Z matrix, then maps grid indices back to world coordinates.

1:1 scale (scaleanchor)

The plot enforces equal data units on both axes:

• xaxis.scaleanchor = 'y'
• xaxis.scaleratio = 1

A 100 m span in X occupies the same screen distance as 100 m in Y. PNG export preserves this constraint. The reference dimension setting controls which pixel edge receives the preset resolution; the other edge is computed from the data/view aspect ratio and layout margins.

Line smoothing

The Smoothness parameter maps to Plotly contour line smoothing (0–1, default 0.85):

• 0 — sharp, piecewise-linear contour segments following grid geometry.
• 1 — maximum curve rounding between vertices (visually smoother arcs).

Smoothing affects the rendered polyline only — it does not change the underlying Z grid or filled colour bands. The fill is drawn between iso-levels on the raw grid; only the line stroke is smoothed.

4. Parameter Reference

Each sidebar control and its effect on Lines contour lines, Area filled heatmap, and Labels contour value labels.

Contour controls

Grid

Points

Background

Cross section

Export & actions

5. PNG Export Options

High-resolution PNG export renders the current plot (including theme, contours, points, backgrounds) via Plotly's image export. The map always preserves 1:1 X/Y data scale.

Resolution presets

The preset value is applied to the reference dimension (see below). The other dimension is computed from aspect ratio. Maximum long edge is capped at 8000 px.

Reference dimension

Example: A2 @ 300 DPI with Height reference on a tall narrow survey → 7016 px tall; width scales proportionally.

Export area

Export process

1. Compute target width/height from preset, reference edge, and extent mode.
2. Temporarily relayout plot: fixed size, theme colours, axis ranges, scaleanchor: 'y', scaleratio: 1.
3. Download PNG via Plotly (contour_plot_YYYY-MM-DD.png).
4. Restore responsive autosize layout.

Dimension formula (data extent mode)

Layout aspect ratio from axis ranges:

where yDomain = 0.86 (0.93 − 0.07) and xDomain = 0.92. If reference = height:

Margins: l=72, r=88, t=52, b=72 pixels (matching on-screen layout).