UXarray logo

Geographic Projections & Features

In this tutorial, you’ll learn about:

  • Selecting appropriate projections for your specific visualization needs

  • Adding geographic features to provide context for your data

  • Customizing projection parameters to optimize your visualizations

Related Documentation

Prerequisites

Concepts

Importance

Notes

Cartopy

Necessary

GeoViews

Helpfull

Time to learn: 5 minutes

Introduction

When visualizing geospatial data on unstructured grids, choosing the right map projection is crucial for accurately representing your data. Geographic projections transform the three-dimensional surface of the Earth onto a two-dimensional plane, each offering different trade-offs between preserving area, distance, direction, or shape.

UXarray leverages Cartopy’s robust projection capabilities to provide flexible geographic visualization options. Through integration with hvPlot and GeoViews, UXarray allows you to easily switch between different projections and add geographic features like coastlines and borders to enhance your visualizations.

We’ll use practical examples to demonstrate these capabilities, focusing on common use cases in climate science, oceanography, and other geophysical applications where unstructured grids are prevalent.

import cartopy.crs as ccrs
import uxarray as ux

grid_path = "../../meshfiles/oQU480.grid.nc"
data_path = "../../meshfiles/oQU480.data.nc"

uxds = ux.open_dataset(grid_path, data_path)

Projections

The geographic projection used for visualization can be specified through the projection parameter in UXarray’s plotting methods. UXarray utilizes Cartopy’s Coordinate Reference System (CRS) objects to define these projections.

The simplest way to set a projection is to create a Cartopy CRS object and pass it to the plotting method.

projection = ccrs.Orthographic()
projection
2025-01-13T00:33:29.719334 image/svg+xml Matplotlib v3.10.0, https://matplotlib.org/ 
<cartopy.crs.Orthographic object at 0x7f54dc419e10>
uxds["bottomDepth"].plot.polygons(projection=projection)

When visualizing data concentrated in specific geographic regions, adjusting the projection’s center point can significantly improve the visualization’s clarity and accuracy. Many projections, including the Orthographic projection, provide central_longitude and central_latitude parameters for this purpose.

This capability is particularly valuable when working with data near the antimeridian (180°/ longitude). For instance, data centered around the Pacific Ocean often crosses this boundary, which can cause visualization artifacts or split features across the edges of the plot. By setting central_longitude=180, you can shift the projection’s center to properly display these regions:

projection = ccrs.Orthographic(central_longitude=-180)
projection
2025-01-13T00:33:34.037204 image/svg+xml Matplotlib v3.10.0, https://matplotlib.org/ 
<cartopy.crs.Orthographic object at 0x7f54cbbc9c90>
uxds["bottomDepth"].plot.polygons(projection=projection)

Features

Geographic features are specified through the features parameter in your plotting command. You can add multiple features by providing them as a list.

Available features include ‘borders’, ‘coastline’, ‘lakes’, ‘land’, ‘ocean’, ‘rivers’ and ‘states’.

uxds["bottomDepth"].plot.polygons(
    projection=projection, features=["borders", "coastline"]
)

/home/runner/miniconda3/envs/unstructured-grid-viz-cookbook-dev/lib/python3.10/site-packages/cartopy/io/__init__.py:241: DownloadWarning: Downloading: https://naturalearth.s3.amazonaws.com/110m_cultural/ne_110m_admin_0_boundary_lines_land.zip
  warnings.warn(f'Downloading: {url}', DownloadWarning)

The resolution of geographic features can be controlled by specifying a scale in the features parameter. This is done by passing a dictionary that maps each feature to its desired scale. There are three resolution levels: ‘10m’ (highest detail), ‘50m’ (medium detail), and ‘110m’ (lowest detail).

uxds["bottomDepth"].plot.polygons(
    projection=projection, features={"borders": "10m", "coastline": "10m"}
)

/home/runner/miniconda3/envs/unstructured-grid-viz-cookbook-dev/lib/python3.10/site-packages/cartopy/io/__init__.py:241: DownloadWarning: Downloading: https://naturalearth.s3.amazonaws.com/10m_physical/ne_10m_coastline.zip
  warnings.warn(f'Downloading: {url}', DownloadWarning)

/home/runner/miniconda3/envs/unstructured-grid-viz-cookbook-dev/lib/python3.10/site-packages/cartopy/io/__init__.py:241: DownloadWarning: Downloading: https://naturalearth.s3.amazonaws.com/10m_cultural/ne_10m_admin_0_boundary_lines_land.zip
  warnings.warn(f'Downloading: {url}', DownloadWarning)
On this page