Top-Tips#

PyProj#

If special transformation grids are included in the coordinate transformation use:

# PROJ activate network grid/data
pyproj.network.set_network_enabled(True)  # pyright: ignore[reportPrivateImportUsage]

Or specify data-dir via

pyproj.datadir.set_data_dir(proj_data_dir)

Results#

The most important functions, mapping(mapper.map_points, mapper.map_footprint, mapper.map_center_point) and coordinate projections (image.project) return MappingResult and ProjectionResult

  • MappingResult is either ResultFailure or MappingResultSuccess

  • ProjectionResult is either ResultFailure or ProjectionResultSuccess

You can test whether it’s Success or Failure be checking .ok. The results will always be in the same order as the input pixel/coordinates.

Always check for issues to catch reasons for invalid results

Errors#

# TODO Check for Errors

Perspective Images#

Tip

For drone photos, prefer building your ImagePerspective from EXIF/XMP metadata (e.g. ExifTool -> PyExifToolTags -> image_from_meta()) or use ImageFromMetaBuilder if you want IOR/EOR separately. See Metadata for Camera and Pose Extraction and 04-01 - Digitize Dugongs.

CRS quick reference#

CRS overview (rows) vs. weitsicht components (columns)#

CRS / units

Perspective Image (EOR)

Orthophoto CRS

Mapper Horizontal

MapperRaster GeorefArray

Mapper Trimesh

None (local coordinates, no transforms)

OK

OK

OK

OK (force_no_crs=True)

OK

Projected/local Cartesian (0)

OK

OK

OK

OK

OK

Geocentric Cartesian (ECEF) (e.g. EPSG:4978)

OK

Not possible - Rare (never seen such thing)

Not possible at the moment (1)

Not possible - Rare (never seen such thing)

OK

Geodetic lon/lat (degrees) (e.g. EPSG:4326 / EPSG:4979)

Not working (2)

Possible (but units for gsd/area are degrees)

Possible (3)

Possible (only with 3D CRS) (4)

Not working (would need transformation first)
(0) has to be 3D CRS or compound, meters (e.g. UTM / EPSG:25833+3855)
(1) ECEF and plane working mathematically but plane normal 0,0,1 makes no sense here. Will implement nonHorizontal plane soon.
(2) use as input CRS and transform to a metric CRS first, also orientation needs to be transformed
(3) using this a lot for sea-side EPSG:4326+3855 -> WGS84 (Lat/Lon) + EGM2008
(4) beware units/vertical datum, very large raster resolutions may lead to problems

Mapping#

For raster-based mapping you can trade disk IO for memory:

  • MappingRaster (default) keeps the raster on disk and reads only the needed values.

  • If you cache a window/full raster (preload_window, preload_full_raster or load_window), MappingRaster automatically uses an in-memory MappingGeorefArray backend.

from pyproj import CRS
from weitsicht import MappingRaster

mapper = MappingRaster(
    raster_path="dem.tif",
    crs=CRS.from_epsg(32633),
    preload_window=(600_000, 5_340_000, 602_000, 5_342_000),
)

# mapper.map_* now uses the cached backend
res = mapper.map_heights_from_coordinates([[601_000, 5_341_000]], crs_s=mapper.crs)

# Or cache later (returns MappingGeorefArray)
georef = mapper.load_window((600_000, 5_340_000, 602_000, 5_342_000))

Important

If you cache only a window, mapping is limited to that cached extent (outside points/rays will report Issue.OUTSIDE_RASTER).