Referencing#
Below, a summary of the georeferencing attributes of geospatial data objects and the methods to manipulate these georeferencing attributes in different projections, without any data transformation. For georeferenced transformations (such as reprojection, cropping), see Transformations.
Attributes#
In GeoUtils, the georeferencing syntax is consistent across all geospatial data objects. Additionally, data objects
load only their metadata by default, allowing quick operations on georeferencing without requiring the array data
(for a Raster) to be present in memory.
Metadata summary#
To summarize all the metadata of a geospatial data object, including its georeferencing, info() can be used:
Show the code for opening example files
import geoutils as gu
rast = gu.Raster(gu.examples.get_path("exploradores_aster_dem"))
vect = gu.Vector(gu.examples.get_path("exploradores_rgi_outlines"))
# Print raster info
rast.info()
Driver: GTiff
Opened from file: /home/docs/checkouts/readthedocs.org/user_builds/geoutils/checkouts/stable/examples/data/Exploradores_ASTER/AST_L1A_00303182012144228_Z.tif
Filename: /home/docs/checkouts/readthedocs.org/user_builds/geoutils/checkouts/stable/examples/data/Exploradores_ASTER/AST_L1A_00303182012144228_Z.tif
Loaded? False
Modified since load? False
Grid size: 539, 618
Number of bands: 1
Data types: float32
Coordinate system: ['EPSG:32718']
Nodata value: -9999.0
Pixel interpretation: Area
Pixel size: 30.0, 30.0
Upper left corner: 627175.0, 4833545.0
Lower right corner: 643345.0, 4852085.0
# Print vector info
vect.info()
Filename: /home/docs/checkouts/readthedocs.org/user_builds/geoutils/checkouts/stable/examples/data/Exploradores_ASTER/17_rgi60_glacier_outlines.gpkg
Coordinate system: EPSG:4326
Extent: [-73.85175999999996, -46.83761999999996, -73.05486243399997, -46.431213112999956]
Number of features: 47
Attributes: ['RGIId', 'GLIMSId', 'BgnDate', 'EndDate', 'CenLon', 'CenLat', 'O1Region', 'O2Region', 'Area', 'Zmin', 'Zmax', 'Zmed', 'Slope', 'Aspect', 'Lmax', 'Status', 'Connect', 'Form', 'TermType', 'Surging', 'Linkages', 'Name', 'geometry']
Coordinate reference systems#
Coordinate reference systems (CRSs), sometimes also called
spatial reference systems (SRSs), define the 2D projection of the geospatial data. They are stored as a
pyproj.crs.CRS object in crs.
# Show CRS attribute of raster
print(rast.crs)
EPSG:32718
# Show CRS attribute of vector as a WKT
print(vect.crs.to_wkt())
GEOGCRS["WGS 84",ENSEMBLE["World Geodetic System 1984 ensemble",MEMBER["World Geodetic System 1984 (Transit)"],MEMBER["World Geodetic System 1984 (G730)"],MEMBER["World Geodetic System 1984 (G873)"],MEMBER["World Geodetic System 1984 (G1150)"],MEMBER["World Geodetic System 1984 (G1674)"],MEMBER["World Geodetic System 1984 (G1762)"],MEMBER["World Geodetic System 1984 (G2139)"],MEMBER["World Geodetic System 1984 (G2296)"],ELLIPSOID["WGS 84",6378137,298.257223563,LENGTHUNIT["metre",1]],ENSEMBLEACCURACY[2.0]],PRIMEM["Greenwich",0,ANGLEUNIT["degree",0.0174532925199433]],CS[ellipsoidal,2],AXIS["geodetic latitude (Lat)",north,ORDER[1],ANGLEUNIT["degree",0.0174532925199433]],AXIS["geodetic longitude (Lon)",east,ORDER[2],ANGLEUNIT["degree",0.0174532925199433]],USAGE[SCOPE["Horizontal component of 3D system."],AREA["World."],BBOX[-90,-180,90,180]],ID["EPSG",4326]]
More information on the manipulation of pyproj.crs.CRS objects can be found in PyProj’s documentation.
Note
3D CRSs for elevation data are only emerging, and not consistently defined in the metadata. The vertical referencing functionalities of xDEM can help define a 3D CRS.
Bounds#
Bounds define the spatial extent of geospatial data, composed of the “left”, “right”, “bottom” and “top” coordinates.
The bounds of a raster or a vector is a rasterio.coords.BoundingBox object:
# Show bounds attribute of raster
rast.bounds
BoundingBox(left=627175.0, bottom=4833545.0, right=643345.0, top=4852085.0)
# Show bounds attribute of vector
vect.bounds
BoundingBox(left=-73.85175999999996, bottom=-46.83761999999996, right=-73.05486243399997, top=-46.431213112999956)
Note
To define bounds consistently between rasters and vectors, bounds
corresponds to geopandas.GeoSeries.total_bounds (total bounds of all geometry features) converted to a rasterio.coords.BoundingBox.
To reproduce the behaviour of geopandas.GeoSeries.bounds (per-feature bounds) with a
Vector, use geom_bounds.
Footprints#
As reprojections between CRSs deform shapes, including extents, it is often better to consider a vectorized footprint
to calculate intersections in different projections. The footprint is a
Vector object with a single polygon geometry for which points have been densified, allowing
reliable computation of extents between CRSs.
# Print raster footprint
rast.get_footprint_projected(rast.crs)
Vector(
ds= geometry
0 POLYGON ((627175 4833545, 627175 4833548.708, ...
crs=PROJCS["WGS 84 / UTM zone 18S",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-75],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",10000000],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","32718"]]
bounds=BoundingBox(left=627175.0, bottom=4833545.0, right=643345.0, top=4852085.0))# Plot vector footprint
vect.get_footprint_projected(vect.crs).plot()
Grid (only for rasters)#
A raster’s grid origin and resolution are defined by its geotransform attribute, transform.
Combined with the 2D shape of the data array shape (and independently of the number of
bands bands), these two attributes define the georeferenced grid of a raster.
From it are derived the resolution res, and height and
width, as well as the bounds detailed above in Bounds.
# Get raster transform and shape
print(rast.transform)
print(rast.shape)
| 30.00, 0.00, 627175.00|
| 0.00,-30.00, 4852085.00|
| 0.00, 0.00, 1.00|
(618, 539)
Pixel interpretation (only for rasters)#
A largely overlooked aspect of a raster’s georeferencing is the pixel interpretation stored in the AREA_OR_POINT metadata. Pixels can be interpreted either as “Area” (the most common) where the value represents a sampling over the region of the pixel (and typically refers to the upper-left corner coordinate), or as “Point” where the value relates to a point sample (and typically refers to the center of the pixel), the latter often used for digital elevation models (DEMs).
Pixel interpretation is stored as a string in the geoutils.Raster.area_or_point attribute.
# Get pixel interpretation of raster
rast.area_or_point
'Area'
Although this interpretation is not intended to influence georeferencing, it can influence sub-pixel coordinate interpretation during analysis, especially for raster–vector–point interfacing operations such as point interpolation, or re-gridding, and might also be a problem if defined differently when comparing two rasters.
Important
By default, pixel interpretation induces a half-pixel shift during raster–point interfacing for a “Point” interpretation (mirroring GDAL’s default ground-control point behaviour), but only raises a warning for raster–raster operations if interpretations differ.
This behaviour can be modified at the package-level by using GeoUtils’ Configuration
shift_area_or_point and warns_area_or_point.
Manipulation#
Several functionalities are available to facilitate the manipulation of the georeferencing.
Getting projected bounds and footprints#
Retrieving projected bounds or footprints in any CRS is possible using directly get_bounds_projected()
and get_footprint_projected().
# Get footprint of larger buffered vector in polar stereo CRS (to show deformations)
vect.buffer_metric(10**6).get_footprint_projected(3995).plot()
Getting a metric CRS#
A local metric coordinate system can be estimated for both Rasters and Vectors through the
get_metric_crs() function.
The metric system returned can be either “universal” (zone of the Universal Transverse Mercator or Universal Polar Stereographic system), or “custom”
(Mercator or Polar projection centered on the Raster or Vector).
# Get local metric CRS
rast.get_metric_crs()
<Projected CRS: EPSG:32718>
Name: WGS 84 / UTM zone 18S
Axis Info [cartesian]:
- E[east]: Easting (metre)
- N[north]: Northing (metre)
Area of Use:
- name: Between 78°W and 72°W, southern hemisphere between 80°S and equator, onshore and offshore. Argentina. Brazil. Chile. Colombia. Ecuador. Peru.
- bounds: (-78.0, -80.0, -72.0, 0.0)
Coordinate Operation:
- name: UTM zone 18S
- method: Transverse Mercator
Datum: World Geodetic System 1984 ensemble
- Ellipsoid: WGS 84
- Prime Meridian: Greenwich
Re-set georeferencing metadata#
The georeferencing metadata of an object can be re-set (overwritten) by setting the corresponding attribute such as geoutils.Vector.crs() or
geoutils.Raster.transform(). When specific options might be useful during setting, a set function exists,
such as for geoutils.Raster.set_area_or_point().
Warning
Re-setting should only be used if the data was erroneously defined and needs to be corrected in-place.
To create geospatial data from its attributes, use the construction functions such as from_array().
# Re-set CRS
import pyproj
rast.crs = pyproj.CRS(4326)
rast.crs
CRS.from_wkt('GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]')
# Re-set pixel interpretation
rast.set_area_or_point("Point")
rast.area_or_point
'Point'
Coordinates to indexes (only for rasters)#
Raster grids are notoriously unintuitive to manipulate on their own due to the Y axis being inverted and stored as first axis. GeoUtils’ features account for this under-the-hood when plotting, interpolating, gridding, or performing any other operation involving the raster coordinates.
Three functions facilitate the manipulation of coordinates, while respecting any Pixel interpretation:
xy2ij()to convert array indices to coordinates,ij2xy()to convert coordinates to array indices (reversible withxy2ij()for any pixel interpretation),coords()to directly obtain coordinates in order corresponding to the data array axes, possibly as a meshgrid.
# Get coordinates from row/columns indices
x, y = rast.ij2xy(i=[0, 1], j=[2, 3])
(x, y)
(array([627235., 627265.]), array([4852085., 4852055.]))
# Get indices from coordinates
i, j = rast.xy2ij(x=x, y=y)
(i, j)
(array([0, 1]), array([2, 3]))
# Get vector X/Y coordinates corresponding to data array
rast.coords(grid=False)
Show code cell output
(array([627175., 627205., 627235., 627265., 627295., 627325., 627355.,
627385., 627415., 627445., 627475., 627505., 627535., 627565.,
627595., 627625., 627655., 627685., 627715., 627745., 627775.,
627805., 627835., 627865., 627895., 627925., 627955., 627985.,
628015., 628045., 628075., 628105., 628135., 628165., 628195.,
628225., 628255., 628285., 628315., 628345., 628375., 628405.,
628435., 628465., 628495., 628525., 628555., 628585., 628615.,
628645., 628675., 628705., 628735., 628765., 628795., 628825.,
628855., 628885., 628915., 628945., 628975., 629005., 629035.,
629065., 629095., 629125., 629155., 629185., 629215., 629245.,
629275., 629305., 629335., 629365., 629395., 629425., 629455.,
629485., 629515., 629545., 629575., 629605., 629635., 629665.,
629695., 629725., 629755., 629785., 629815., 629845., 629875.,
629905., 629935., 629965., 629995., 630025., 630055., 630085.,
630115., 630145., 630175., 630205., 630235., 630265., 630295.,
630325., 630355., 630385., 630415., 630445., 630475., 630505.,
630535., 630565., 630595., 630625., 630655., 630685., 630715.,
630745., 630775., 630805., 630835., 630865., 630895., 630925.,
630955., 630985., 631015., 631045., 631075., 631105., 631135.,
631165., 631195., 631225., 631255., 631285., 631315., 631345.,
631375., 631405., 631435., 631465., 631495., 631525., 631555.,
631585., 631615., 631645., 631675., 631705., 631735., 631765.,
631795., 631825., 631855., 631885., 631915., 631945., 631975.,
632005., 632035., 632065., 632095., 632125., 632155., 632185.,
632215., 632245., 632275., 632305., 632335., 632365., 632395.,
632425., 632455., 632485., 632515., 632545., 632575., 632605.,
632635., 632665., 632695., 632725., 632755., 632785., 632815.,
632845., 632875., 632905., 632935., 632965., 632995., 633025.,
633055., 633085., 633115., 633145., 633175., 633205., 633235.,
633265., 633295., 633325., 633355., 633385., 633415., 633445.,
633475., 633505., 633535., 633565., 633595., 633625., 633655.,
633685., 633715., 633745., 633775., 633805., 633835., 633865.,
633895., 633925., 633955., 633985., 634015., 634045., 634075.,
634105., 634135., 634165., 634195., 634225., 634255., 634285.,
634315., 634345., 634375., 634405., 634435., 634465., 634495.,
634525., 634555., 634585., 634615., 634645., 634675., 634705.,
634735., 634765., 634795., 634825., 634855., 634885., 634915.,
634945., 634975., 635005., 635035., 635065., 635095., 635125.,
635155., 635185., 635215., 635245., 635275., 635305., 635335.,
635365., 635395., 635425., 635455., 635485., 635515., 635545.,
635575., 635605., 635635., 635665., 635695., 635725., 635755.,
635785., 635815., 635845., 635875., 635905., 635935., 635965.,
635995., 636025., 636055., 636085., 636115., 636145., 636175.,
636205., 636235., 636265., 636295., 636325., 636355., 636385.,
636415., 636445., 636475., 636505., 636535., 636565., 636595.,
636625., 636655., 636685., 636715., 636745., 636775., 636805.,
636835., 636865., 636895., 636925., 636955., 636985., 637015.,
637045., 637075., 637105., 637135., 637165., 637195., 637225.,
637255., 637285., 637315., 637345., 637375., 637405., 637435.,
637465., 637495., 637525., 637555., 637585., 637615., 637645.,
637675., 637705., 637735., 637765., 637795., 637825., 637855.,
637885., 637915., 637945., 637975., 638005., 638035., 638065.,
638095., 638125., 638155., 638185., 638215., 638245., 638275.,
638305., 638335., 638365., 638395., 638425., 638455., 638485.,
638515., 638545., 638575., 638605., 638635., 638665., 638695.,
638725., 638755., 638785., 638815., 638845., 638875., 638905.,
638935., 638965., 638995., 639025., 639055., 639085., 639115.,
639145., 639175., 639205., 639235., 639265., 639295., 639325.,
639355., 639385., 639415., 639445., 639475., 639505., 639535.,
639565., 639595., 639625., 639655., 639685., 639715., 639745.,
639775., 639805., 639835., 639865., 639895., 639925., 639955.,
639985., 640015., 640045., 640075., 640105., 640135., 640165.,
640195., 640225., 640255., 640285., 640315., 640345., 640375.,
640405., 640435., 640465., 640495., 640525., 640555., 640585.,
640615., 640645., 640675., 640705., 640735., 640765., 640795.,
640825., 640855., 640885., 640915., 640945., 640975., 641005.,
641035., 641065., 641095., 641125., 641155., 641185., 641215.,
641245., 641275., 641305., 641335., 641365., 641395., 641425.,
641455., 641485., 641515., 641545., 641575., 641605., 641635.,
641665., 641695., 641725., 641755., 641785., 641815., 641845.,
641875., 641905., 641935., 641965., 641995., 642025., 642055.,
642085., 642115., 642145., 642175., 642205., 642235., 642265.,
642295., 642325., 642355., 642385., 642415., 642445., 642475.,
642505., 642535., 642565., 642595., 642625., 642655., 642685.,
642715., 642745., 642775., 642805., 642835., 642865., 642895.,
642925., 642955., 642985., 643015., 643045., 643075., 643105.,
643135., 643165., 643195., 643225., 643255., 643285., 643315.]),
array([4833575., 4833605., 4833635., 4833665., 4833695., 4833725.,
4833755., 4833785., 4833815., 4833845., 4833875., 4833905.,
4833935., 4833965., 4833995., 4834025., 4834055., 4834085.,
4834115., 4834145., 4834175., 4834205., 4834235., 4834265.,
4834295., 4834325., 4834355., 4834385., 4834415., 4834445.,
4834475., 4834505., 4834535., 4834565., 4834595., 4834625.,
4834655., 4834685., 4834715., 4834745., 4834775., 4834805.,
4834835., 4834865., 4834895., 4834925., 4834955., 4834985.,
4835015., 4835045., 4835075., 4835105., 4835135., 4835165.,
4835195., 4835225., 4835255., 4835285., 4835315., 4835345.,
4835375., 4835405., 4835435., 4835465., 4835495., 4835525.,
4835555., 4835585., 4835615., 4835645., 4835675., 4835705.,
4835735., 4835765., 4835795., 4835825., 4835855., 4835885.,
4835915., 4835945., 4835975., 4836005., 4836035., 4836065.,
4836095., 4836125., 4836155., 4836185., 4836215., 4836245.,
4836275., 4836305., 4836335., 4836365., 4836395., 4836425.,
4836455., 4836485., 4836515., 4836545., 4836575., 4836605.,
4836635., 4836665., 4836695., 4836725., 4836755., 4836785.,
4836815., 4836845., 4836875., 4836905., 4836935., 4836965.,
4836995., 4837025., 4837055., 4837085., 4837115., 4837145.,
4837175., 4837205., 4837235., 4837265., 4837295., 4837325.,
4837355., 4837385., 4837415., 4837445., 4837475., 4837505.,
4837535., 4837565., 4837595., 4837625., 4837655., 4837685.,
4837715., 4837745., 4837775., 4837805., 4837835., 4837865.,
4837895., 4837925., 4837955., 4837985., 4838015., 4838045.,
4838075., 4838105., 4838135., 4838165., 4838195., 4838225.,
4838255., 4838285., 4838315., 4838345., 4838375., 4838405.,
4838435., 4838465., 4838495., 4838525., 4838555., 4838585.,
4838615., 4838645., 4838675., 4838705., 4838735., 4838765.,
4838795., 4838825., 4838855., 4838885., 4838915., 4838945.,
4838975., 4839005., 4839035., 4839065., 4839095., 4839125.,
4839155., 4839185., 4839215., 4839245., 4839275., 4839305.,
4839335., 4839365., 4839395., 4839425., 4839455., 4839485.,
4839515., 4839545., 4839575., 4839605., 4839635., 4839665.,
4839695., 4839725., 4839755., 4839785., 4839815., 4839845.,
4839875., 4839905., 4839935., 4839965., 4839995., 4840025.,
4840055., 4840085., 4840115., 4840145., 4840175., 4840205.,
4840235., 4840265., 4840295., 4840325., 4840355., 4840385.,
4840415., 4840445., 4840475., 4840505., 4840535., 4840565.,
4840595., 4840625., 4840655., 4840685., 4840715., 4840745.,
4840775., 4840805., 4840835., 4840865., 4840895., 4840925.,
4840955., 4840985., 4841015., 4841045., 4841075., 4841105.,
4841135., 4841165., 4841195., 4841225., 4841255., 4841285.,
4841315., 4841345., 4841375., 4841405., 4841435., 4841465.,
4841495., 4841525., 4841555., 4841585., 4841615., 4841645.,
4841675., 4841705., 4841735., 4841765., 4841795., 4841825.,
4841855., 4841885., 4841915., 4841945., 4841975., 4842005.,
4842035., 4842065., 4842095., 4842125., 4842155., 4842185.,
4842215., 4842245., 4842275., 4842305., 4842335., 4842365.,
4842395., 4842425., 4842455., 4842485., 4842515., 4842545.,
4842575., 4842605., 4842635., 4842665., 4842695., 4842725.,
4842755., 4842785., 4842815., 4842845., 4842875., 4842905.,
4842935., 4842965., 4842995., 4843025., 4843055., 4843085.,
4843115., 4843145., 4843175., 4843205., 4843235., 4843265.,
4843295., 4843325., 4843355., 4843385., 4843415., 4843445.,
4843475., 4843505., 4843535., 4843565., 4843595., 4843625.,
4843655., 4843685., 4843715., 4843745., 4843775., 4843805.,
4843835., 4843865., 4843895., 4843925., 4843955., 4843985.,
4844015., 4844045., 4844075., 4844105., 4844135., 4844165.,
4844195., 4844225., 4844255., 4844285., 4844315., 4844345.,
4844375., 4844405., 4844435., 4844465., 4844495., 4844525.,
4844555., 4844585., 4844615., 4844645., 4844675., 4844705.,
4844735., 4844765., 4844795., 4844825., 4844855., 4844885.,
4844915., 4844945., 4844975., 4845005., 4845035., 4845065.,
4845095., 4845125., 4845155., 4845185., 4845215., 4845245.,
4845275., 4845305., 4845335., 4845365., 4845395., 4845425.,
4845455., 4845485., 4845515., 4845545., 4845575., 4845605.,
4845635., 4845665., 4845695., 4845725., 4845755., 4845785.,
4845815., 4845845., 4845875., 4845905., 4845935., 4845965.,
4845995., 4846025., 4846055., 4846085., 4846115., 4846145.,
4846175., 4846205., 4846235., 4846265., 4846295., 4846325.,
4846355., 4846385., 4846415., 4846445., 4846475., 4846505.,
4846535., 4846565., 4846595., 4846625., 4846655., 4846685.,
4846715., 4846745., 4846775., 4846805., 4846835., 4846865.,
4846895., 4846925., 4846955., 4846985., 4847015., 4847045.,
4847075., 4847105., 4847135., 4847165., 4847195., 4847225.,
4847255., 4847285., 4847315., 4847345., 4847375., 4847405.,
4847435., 4847465., 4847495., 4847525., 4847555., 4847585.,
4847615., 4847645., 4847675., 4847705., 4847735., 4847765.,
4847795., 4847825., 4847855., 4847885., 4847915., 4847945.,
4847975., 4848005., 4848035., 4848065., 4848095., 4848125.,
4848155., 4848185., 4848215., 4848245., 4848275., 4848305.,
4848335., 4848365., 4848395., 4848425., 4848455., 4848485.,
4848515., 4848545., 4848575., 4848605., 4848635., 4848665.,
4848695., 4848725., 4848755., 4848785., 4848815., 4848845.,
4848875., 4848905., 4848935., 4848965., 4848995., 4849025.,
4849055., 4849085., 4849115., 4849145., 4849175., 4849205.,
4849235., 4849265., 4849295., 4849325., 4849355., 4849385.,
4849415., 4849445., 4849475., 4849505., 4849535., 4849565.,
4849595., 4849625., 4849655., 4849685., 4849715., 4849745.,
4849775., 4849805., 4849835., 4849865., 4849895., 4849925.,
4849955., 4849985., 4850015., 4850045., 4850075., 4850105.,
4850135., 4850165., 4850195., 4850225., 4850255., 4850285.,
4850315., 4850345., 4850375., 4850405., 4850435., 4850465.,
4850495., 4850525., 4850555., 4850585., 4850615., 4850645.,
4850675., 4850705., 4850735., 4850765., 4850795., 4850825.,
4850855., 4850885., 4850915., 4850945., 4850975., 4851005.,
4851035., 4851065., 4851095., 4851125., 4851155., 4851185.,
4851215., 4851245., 4851275., 4851305., 4851335., 4851365.,
4851395., 4851425., 4851455., 4851485., 4851515., 4851545.,
4851575., 4851605., 4851635., 4851665., 4851695., 4851725.,
4851755., 4851785., 4851815., 4851845., 4851875., 4851905.,
4851935., 4851965., 4851995., 4852025., 4852055., 4852085.]))