Surface Normals#

Many mapping operations in weitsicht return surface normals as part of MappingResultSuccess (field normals).

Normals are returned as:

  • a numpy array of shape (N, 3),

  • unit vectors in the same CRS as coordinates,

  • nan for entries where mask is False.

They are primarily used to refine perspective-image GSD estimation (see Perspective Image).

How normals are estimated (by mapper)#

The meaning of normals depends on the mapper backend:

Normal estimation per mapper#

Mapper

Normal estimation

MappingHorizontalPlane

Constant upward normal (0, 0, 1) in mapper CRS (then transformed).

MappingRaster (disk-backed)

Currently returns the local “up” direction of the mapper CRS (i.e. (0, 0, 1) transformed back to the source CRS). It does not encode DEM slope yet.

MappingGeorefArray (in-memory)

Same as above: currently returns the local “up” direction of the mapper CRS.

MappingTrimesh

Uses the hit triangle’s face normal (from trimesh), oriented to face against the ray direction (towards the ray origin). If normals are unavailable/invalid, a fallback uses the reverse ray direction as an approximate normal.

CRS notes#

Normals are direction vectors and cannot be transformed by many CRS operations directly. When a CRS transform is required, weitsicht approximates vector transformation by:

  1. transforming a start point p and an end point p + v_unit * 10, and

  2. re-normalizing the transformed difference vector.

This works best in cartesian-like CRSs with linear units (meters), such as projected CRSs or ECEF. For geographic CRSs (lon/lat degrees) the concept of “unit vectors” and angles becomes ambiguous; treat normals and any derived quantities (like incidence-angle corrections) with care.

Note

Raster-based mappers currently approximate normals as a purely vertical “up” vector. In many geographic 3D CRSs (lon/lat/height, e.g. WGS84 3D / EPSG:4979), the height axis is a linear unit (typically meters), so transforming a purely vertical vector is often stable even though the horizontal axes are in degrees.

This only addresses the vector transform itself; it does not make angle- or distance-based interpretations in a geographic CRS physically meaningful. For measurements (GSD, areas, incidence angles), prefer a projected metric CRS.