update doc from

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 3c29c526d69f6ad9f45ce2532034e3fe
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_downloads/326f1e4f381185b5da31cfd0fc7fb40e/latlon_to_healpix.py

@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+HealPIX regridding
+------------------
+
+In this notebook, I demonstrate bilinear regridding onto healpy grids in O(10)
+ms. this is a 3 order of magnitude speed-up compared to what Dale has reported.
+
+Now, lets define a healpix grid with indexing in the XY convention. we convert
+to NEST indexing in order to use the `healpy.pix2ang` to get the lat lon
+coordinates. This operation is near instant.
+
+"""
+# %%
+
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+
+import earth2grid
+
+# level is the resolution
+level = 6
+hpx = earth2grid.healpix.Grid(level=level, pixel_order=earth2grid.healpix.XY())
+src = earth2grid.latlon.equiangular_lat_lon_grid(32, 64)
+regrid = earth2grid.get_regridder(src, hpx)
+
+
+z = np.cos(np.deg2rad(src.lat)) * np.cos(np.deg2rad(src.lon))
+
+
+z_torch = torch.as_tensor(z)
+z_hpx = regrid(z_torch)
+
+fig, (a, b) = plt.subplots(2, 1)
+a.pcolormesh(src.lon, src.lat, z)
+a.set_title("Lat Lon Grid")
+
+b.scatter(hpx.lon, hpx.lat, c=z_hpx, s=0.1)
+b.set_title("Healpix")
+
+# %% one tile
+nside = 2**level
+reshaped = z_hpx.reshape(12, nside, nside)
+lat_r = hpx.lat.reshape(12, nside, nside)
+lon_r = hpx.lon.reshape(12, nside, nside)
+
+tile = 11
+fig, axs = plt.subplots(3, 4, sharex=True, sharey=True)
+axs = axs.ravel()
+
+for tile in range(12):
+    axs[tile].pcolormesh(lon_r[tile], lat_r[tile], reshaped[tile])

_downloads/9b0d4977029b26f04ef1efed15239f54/hpx2grid.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+HealPIX Image visualization
+---------------------------
+
+HealPIX maps can be viewed as a 2D image rotated by 45 deg. This is useful for
+quick visualization with image viewers without distorting the native pixels of
+the image.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+
+# %%
+from matplotlib.colors import Normalize
+from PIL import Image
+
+from earth2grid.healpix import Grid
+
+grid = Grid(level=8)
+lat = torch.tensor(grid.lat)
+lat_img = grid.to_image(lat)
+
+# Use Image to save at full resolution
+normalizer = Normalize(vmin=np.nanmin(lat_img), vmax=np.nanmax(lat_img))
+array = normalizer(lat_img)
+array = plt.cm.viridis(array)
+array = (256 * array).astype("uint8")
+# set transparency for nans
+array[..., -1] = np.where(np.isnan(lat_img), 0, 255)
+image = Image.fromarray(array)
+image.save("hpx_grid.png")

_downloads/a0fb23b6404ea0f060e2ee086a2a1fd2/pyvista_grids.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Plot grids with PyVista
+-----------------------
+
+"""
+import pyvista as pv
+
+# %%
+import earth2grid
+
+
+def label(mesh, plotter, text):
+    """
+    Add a label above a mesh in a PyVista plot.
+
+    Parameters:
+    - mesh: The mesh to label.
+    - plotter: A PyVista plotter instance.
+    - text: The label text.
+    - color: The color of the text label. Default is 'white'.
+    """
+    # Calculate the center of the mesh and the top Z-coordinate plus an offset
+    center = mesh.center
+    label_pos = [center[0], center[1], mesh.bounds[5] + 0.5]  # Offset to place label above the mesh
+
+    # Add the label using point labels for precise 3D positioning
+    plotter.add_point_labels(
+        [label_pos], [text], point_size=0, render_points_as_spheres=False, shape_opacity=0, font_size=20
+    )
+
+
+grid = earth2grid.healpix.Grid(level=4)
+hpx = grid.to_pyvista()
+latlon = earth2grid.latlon.equiangular_lat_lon_grid(32, 64, includes_south_pole=False).to_pyvista()
+
+
+pl = pv.Plotter()
+mesh = hpx.translate([0, 2.5, 0])
+pl.add_mesh(mesh, show_edges=True)
+label(mesh, pl, "HealPix")
+
+pl.add_mesh(latlon, show_edges=True)
+label(latlon, pl, "Equiangular Lat/Lon")
+
+pl.camera.position = (5, 0, 5)
+pl.show()

_downloads/bc5f3d8ff2e85ce704e6bc194c4a1825/pyvista_grids.ipynb

@@ -0,0 +1,54 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Plot grids with PyVista\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import pyvista as pv"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import earth2grid\n\n\ndef label(mesh, plotter, text):\n    \"\"\"\n    Add a label above a mesh in a PyVista plot.\n\n    Parameters:\n    - mesh: The mesh to label.\n    - plotter: A PyVista plotter instance.\n    - text: The label text.\n    - color: The color of the text label. Default is 'white'.\n    \"\"\"\n    # Calculate the center of the mesh and the top Z-coordinate plus an offset\n    center = mesh.center\n    label_pos = [center[0], center[1], mesh.bounds[5] + 0.5]  # Offset to place label above the mesh\n\n    # Add the label using point labels for precise 3D positioning\n    plotter.add_point_labels(\n        [label_pos], [text], point_size=0, render_points_as_spheres=False, shape_opacity=0, font_size=20\n    )\n\n\ngrid = earth2grid.healpix.Grid(level=4)\nhpx = grid.to_pyvista()\nlatlon = earth2grid.latlon.equiangular_lat_lon_grid(32, 64, includes_south_pole=False).to_pyvista()\n\n\npl = pv.Plotter()\nmesh = hpx.translate([0, 2.5, 0])\npl.add_mesh(mesh, show_edges=True)\nlabel(mesh, pl, \"HealPix\")\n\npl.add_mesh(latlon, show_edges=True)\nlabel(latlon, pl, \"Equiangular Lat/Lon\")\n\npl.camera.position = (5, 0, 5)\npl.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.11.3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

_downloads/ceda851f459aa1125447c51ea42b0e9e/hpx2grid.ipynb

@@ -0,0 +1,54 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# HealPIX Image visualization\n\nHealPIX maps can be viewed as a 2D image rotated by 45 deg. This is useful for\nquick visualization with image viewers without distorting the native pixels of\nthe image.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import matplotlib.pyplot as plt\nimport numpy as np\nimport torch"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from matplotlib.colors import Normalize\nfrom PIL import Image\n\nfrom earth2grid.healpix import Grid\n\ngrid = Grid(level=8)\nlat = torch.tensor(grid.lat)\nlat_img = grid.to_image(lat)\n\n# Use Image to save at full resolution\nnormalizer = Normalize(vmin=np.nanmin(lat_img), vmax=np.nanmax(lat_img))\narray = normalizer(lat_img)\narray = plt.cm.viridis(array)\narray = (256 * array).astype(\"uint8\")\n# set transparency for nans\narray[..., -1] = np.where(np.isnan(lat_img), 0, 255)\nimage = Image.fromarray(array)\nimage.save(\"hpx_grid.png\")"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.11.3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

_downloads/f6888b7c20ca92b13107eb2bef6349b7/latlon_to_healpix.ipynb

@@ -0,0 +1,54 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# HealPIX regridding\n\nIn this notebook, I demonstrate bilinear regridding onto healpy grids in O(10)\nms. this is a 3 order of magnitude speed-up compared to what Dale has reported.\n\nNow, lets define a healpix grid with indexing in the XY convention. we convert\nto NEST indexing in order to use the `healpy.pix2ang` to get the lat lon\ncoordinates. This operation is near instant.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import matplotlib.pyplot as plt\nimport numpy as np\nimport torch\n\nimport earth2grid\n\n# level is the resolution\nlevel = 6\nhpx = earth2grid.healpix.Grid(level=level, pixel_order=earth2grid.healpix.XY())\nsrc = earth2grid.latlon.equiangular_lat_lon_grid(32, 64)\nregrid = earth2grid.get_regridder(src, hpx)\n\n\nz = np.cos(np.deg2rad(src.lat)) * np.cos(np.deg2rad(src.lon))\n\n\nz_torch = torch.as_tensor(z)\nz_hpx = regrid(z_torch)\n\nfig, (a, b) = plt.subplots(2, 1)\na.pcolormesh(src.lon, src.lat, z)\na.set_title(\"Lat Lon Grid\")\n\nb.scatter(hpx.lon, hpx.lat, c=z_hpx, s=0.1)\nb.set_title(\"Healpix\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "nside = 2**level\nreshaped = z_hpx.reshape(12, nside, nside)\nlat_r = hpx.lat.reshape(12, nside, nside)\nlon_r = hpx.lon.reshape(12, nside, nside)\n\ntile = 11\nfig, axs = plt.subplots(3, 4, sharex=True, sharey=True)\naxs = axs.ravel()\n\nfor tile in range(12):\n    axs[tile].pcolormesh(lon_r[tile], lat_r[tile], reshaped[tile])"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.11.3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

_sources/api.rst.txt

@@ -0,0 +1,25 @@
+API
+===
+
+Grids
+-----
+
+.. autoclass:: earth2grid.healpix.Grid
+   :members:
+   :show-inheritance:
+
+.. autoclass:: earth2grid.latlon.LatLonGrid
+   :members:
+   :show-inheritance:
+
+.. autofunction:: earth2grid.latlon.equiangular_lat_lon_grid
+
+Regridding
+----------
+
+.. autofunction:: earth2grid.get_regridder
+
+Other utilities
+---------------
+
+.. autofunction:: earth2grid.healpix.pad