mdtanker · mdtanker · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026 · Aug 6, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -34,6 +34,23 @@ Contributors:
 
 -->
 
+## Unreleased
+
+### 🚀 Added
+- new parameter `rotation` for `plot_grid`, `basemap`, `Figure` and `set_proj`, to rotate a map clockwise by a given number of degrees instead of always using the projection's own orientation. The plotted region is expanded to the bounding box of the rotated region, so nothing is cut off; this means a rotated figure is larger than an unrotated one. When no region is given, the map is zoomed to fit the data. Only available for polar stereographic projections (EPSG:3031 and EPSG:3413).
+- `region` for `plot_grid`, `basemap` and `Figure` now also accepts corner coordinates, which unlike a `[xmin, xmax, ymin, ymax]` region can describe a *tilted* box. The rotation is then inferred from the corners, so it needn't be given.
+- new function `oriented_region` returning the smallest rotated rectangle around an outline: the rotation which squares it up, its corners, the region the map will show, and the region to fetch data for. Accepts a shapefile path, a GeoDataFrame, a DataFrame, the output of `draw_region`, or coordinate arrays, and takes a `pad` to zoom out from a box which is otherwise the tightest possible. This is the rotated counterpart of `polygon_to_region`; for the Getz Ice Shelf outline it plots 2.2x less area. Four quarter turns square a box up equally well, so the one returned lays the long axis across the page with true north nearest the top; add 90 or 180 to `rotation` for any of the others.
+- new function `unrotated_region` giving the region of data needed to fully cover a rotated map, since its footprint is a tilted rectangle in the unrotated projection. Also available on a figure as `Figure.reg_base`.
+- new functions `native_top_longitude`, `rotation_to_top_longitude` and `top_longitude_to_rotation`, since rotating is equivalent to choosing which line of longitude is at the top of the page. Also available on a figure as `Figure.top_longitude`.
+- new functions `rotated_crs`, `rotated_central_meridian`, `rotation_transformer`, `rotate_region`, `region_corners` and `normalize_rotation` supporting the above
+- `rotate_region` and `unrotated_region` take `rotation` before the optional `hemisphere`/`epsg`, matching the rest of the library, so the hemisphere can come from the `POLARTOOLKIT_HEMISPHERE` environment variable
+- added `rasterio` as an explicit dependency; it was already required transitively by `rioxarray` and is now imported directly
+
+### ✏️ Changed
+- `add_box` now draws the region as a quadrilateral rather than an axis-aligned rectangle, so it stays correct on a rotated map
+- two `plot` calls in `add_simple_basemap` now pass `projection` and `region` explicitly instead of relying on GMT's ambient state
+- `add_inset` now determines its region from the stored figure region rather than PyGMT's live GMT state, which inside the inset context was not the main map's region
+
 ## v1.5.1
 Released on 2026-03-22
 Contributors:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -42,28 +42,40 @@ contributions.
 
 ## Contents
 
-* [What Can I Do?](#what-can-i-do)
-* [Reporting a Bug](#reporting-a-bug)
-* [Editing the Documentation](#editing-the-documentation)
-* [Contributing Code](#contributing-code)
-  - [General guidelines](#general-guidelines)
-  - [Fork the repository](#fork-the-repository)
-  - [Clone the repository](#clone-the-repository)
-  - [Setting up your environment](#setting-up-your-environment)
-  - [Make a branch](#make-a-branch)
-  - [Make your changes](#make-your-changes)
-  - [Testing your code](#testing-your-code)
-  - [Documentation](#documentation)
-  - [Committing changes](#committing-changes)
-  - [Push your changes](#push-your-changes)
-  - [Open a PR](#open-a-pr)
-  - [Code review](#code-review)
-  - [Sync your fork and local](#sync-your-fork-and-local)
-  - [Add yourself as an author](#add-yourself-as-an-author)
-* [Publish a new release](#publish-a-new-release)
-* [Update the Dependencies](#update-the-dependencies)
-* [Create a conda environment file](#create-a-conda-environment-file)
-* [Set up the binder configuration](#set-up-the-binder-configuration)
+- [How to contribute](#how-to-contribute)
+  - [TLDR (Too long; didn't read)](#tldr-too-long-didnt-read)
+  - [Contents](#contents)
+  - [What Can I Do?](#what-can-i-do)
+  - [Reporting a Bug](#reporting-a-bug)
+  - [Editing the Documentation](#editing-the-documentation)
+  - [Contributing Code](#contributing-code)
+    - [General guidelines](#general-guidelines)
+    - [Fork the repository](#fork-the-repository)
+    - [Clone the repository](#clone-the-repository)
+    - [Setting up your environment](#setting-up-your-environment)
+    - [Make a branch](#make-a-branch)
+    - [Make your changes](#make-your-changes)
+      - [Code style and linting](#code-style-and-linting)
+      - [Docstrings](#docstrings)
+      - [Type hints](#type-hints)
+      - [Logging](#logging)
+    - [Testing your code](#testing-your-code)
+    - [Documentation](#documentation)
+      - [Run all .ipynb's to update them](#run-all-ipynbs-to-update-them)
+      - [Check the build manually (optional)](#check-the-build-manually-optional)
+      - [Automatically build the docs](#automatically-build-the-docs)
+    - [Committing changes](#committing-changes)
+    - [Push your changes](#push-your-changes)
+    - [Open a PR](#open-a-pr)
+    - [Code review](#code-review)
+    - [Sync your fork and local](#sync-your-fork-and-local)
+    - [Add yourself as an author](#add-yourself-as-an-author)
+  - [Publish a new release](#publish-a-new-release)
+    - [PyPI (pip)](#pypi-pip)
+    - [Conda-Forge](#conda-forge)
+  - [Update the dependencies](#update-the-dependencies)
+  - [Create a conda environment file](#create-a-conda-environment-file)
+  - [Set up the binder configuration](#set-up-the-binder-configuration)
 
 ## What Can I Do?
 
@@ -173,21 +185,14 @@ Now we need to configure Git to sync this fork to the main repository, not your
 git remote add upstream https://github.com/mdtanker/polartoolkit.git
 ```
 
-### Setting up `nox`
-
-Most of the commands used in the development of `polartoolkit` use the tool `nox`.
-The `nox` commands are defined in the file [`noxfile.py`](https://github.com/mdtanker/polartoolkit/blob/main/noxfile.py), and are run in the terminal / command prompt with the format ```nox -s <<command name>>```.
-
-You can install nox with `pip install nox`.
-
 ### Setting up your environment
 
 We use `pixi` to manage our dependencies and to run certain workflows, like style-checking the code and building the documentation.
 If you don't have `pixi`, see the install instructions [here](https://pixi.prefix.dev/latest/installation/).
 
 Run `pixi install` to set up your environments.
 
-This contains your local, editable version of airbornegeo, meaning if you alter code in the package, it will automatically include those changes in your environment (you may need to restart your kernel if using Jupyter). If you need to update the dependencies, see the [update the dependencies](#update-the-dependencies) section below.
+This contains your local, editable version of PolarToolkit, meaning if you alter code in the package, it will automatically include those changes in your environment (you may need to restart your kernel if using Jupyter). If you need to update the dependencies, see the [update the dependencies](#update-the-dependencies) section below.
 
 ### Make a branch
 

diff --git a/docs/api/polartoolkit.rst b/docs/api/polartoolkit.rst
@@ -134,6 +134,17 @@ Here are a few utility functions which can be helpful for plotting.
 
    square_subplots
    set_proj
+   rotated_crs
+   rotated_central_meridian
+   rotation_transformer
+   rotate_region
+   region_corners
+   native_top_longitude
+   top_longitude_to_rotation
+   rotation_to_top_longitude
+   unrotated_region
+   oriented_region
+   normalize_rotation
    random_color
    get_fig_height
    get_fig_width

diff --git a/docs/gallery/setting_projection.ipynb b/docs/gallery/setting_projection.ipynb
@@ -880,7 +880,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.11"
+   "version": "3.12.13"
   }
  },
  "nbformat": 4,

diff --git a/docs/how_to/index.md b/docs/how_to/index.md
@@ -7,6 +7,7 @@ download_NASA_data
 basemaps
 switch_between_hemispheres
 plotting_non_polar_regions
+rotating_maps
 defining_regions
 manipulating_regions
 use_with_pygmt

diff --git a/docs/how_to/rotating_maps.ipynb b/docs/how_to/rotating_maps.ipynb