Skip to main content

Package to streamline operations with GOES satellite imagery

Project description

PyPI - Version
PyPI - Downloads GitHub License GitHub repo size

GoesVideo


This package is a convenience wrapper for Satpy to facilitate quick and simple creation of animated scenes from the GOES geostationary satellites. It handles downloading, compositing and animating of GOES imagery. Also, editing tools are provided to perform georeferenced manipulations and annotations of animated scenes.

Installation


GoesVideo can be installed from PyPi using pip:

pip install goesvideo

Example Usage


To highlight the capabilities of GoesVideo, we will look at some GOES-East imagery near Big Horn, WY during the time period of early October 2024 when several large wildfires erupted.

First, we define the bounding box coordinates for the area of interest in the order of (west, south, east, north):

bbox = (-108.09, 43.794, -106.43, 45.25)

Next, we can easily create composite images and video of this area in the time frame of interest:

from goesvideo import GoesAnimator
from pathlib import Path

basedir = str(Path.home()) + '/goesimagery'
am = GoesAnimator('goes-east', 'conus', 'ABI-L2-CMIP', base_dir=basedir)
# Adding coastlines requires shapefile path to be specified
# Shapefiles can be downloaded here: https://www.soest.hawaii.edu/pwessel/gshhg/
coastopts = {'level_coast': 1, 'level_borders': 2}
am.compositor.set_coastlines_options(path=coastpath, **coastopts)
am.create_video('true_color_with_night_ir_custom',
                start_time='2024-10-08 12:00:00',
                end_time='2024-10-11 05:00:00',
                folder_name='Big_Horn_WY',
                bbox=bbox,
                interval=1,
                coastlines=True,
                res='auto',
                codec='rawvideo',
                fps=20
                )

That's all there is to it! Here's a screenshot of one of the composited images:

title

Now, let's add some annotations to the image frames in our video:

from goesvideo.addons.sceneeditor import GoesSceneEditor

editor = GoesSceneEditor(basedir, 'Big_Horn_WY', session_name='Big_Horn_WY_edit1')
# fontpath should be path to a ttf font
editor.set_font(fontpath, (255, 0, 0), 20)

# Add timestamp to each video frame
editor.add_timestamps('upper-left', pytz.timezone('US/Mountain'), preview=False)

# Add circle at specified lat/lon position
circleopts = {"radius": 7, "fill": (0, 0, 255), "outline": (0, 0, 0), "width": 1}
editor.add_annotation(
    "circle",
    ("44d21m56s N", "107d10m28s W"),
    label="3504m elev.",
    labelopts={"fontsize": 15, "padding": (15, 15)},
    **circleopts,
)
editor.process_annotations(preview=False)
editor.to_video(codec='rawvideo', fps=20)

The GoesSceneEditor copies over the composited images from the Big_Horn_WY folder to a designated session folder where annotations can be applied. After all of the images have been edited, a new output video is created. Here is a screenshot:

title

If desired, further modifications can be made by GoesSceneEditor including recropping to new boundary coordinates, resizing and reprojection in a different CRS.

editor.recrop((-107, 44, -106.9, 44), preview=False)
editor.resize(1024, 768, preview=False)
editor.reproject("EPSG:4326", preview=False)

Finally, GoesSceneEditor can produce overlay videos using images from another editor instance. This can be useful when visualizing hot spots detected by the FDC product available from the GOES ABI.

fdc_comp = GoesCompositor('goes-east', 'conus', 'ABI-L2-FDC', base_dir=basedir)
fdc_comp.create_composites('Power',
                           start_time='2024-10-08 12:00:00',
                           end_time='2024-10-11 05:00:00',
                           folder_name='Big_Horn_WY_Fire_Detection',
                           bbox=bbox,
                           output_format='geotiff'
                           )
oleditor = GoesSceneEditor(basedir, 'Big_Horn_WY_Fire_Detection', session_name='Big_Horn_WY_Fire_Edit_1')
editor.add_overlay(oleditor, opacity=0.8, cumulative=True, overlay_session_name='Big_Horn_Overlay')
editor.to_video(codec='rawvideo', fps=20)

The output video shows the fire detection overlay as red pixels. The cumulative option forces a hotspot to remain in the video after its first appearance.

title

Finally, a note about the folder structure used by GoesVideo. There are four primary folders that are generated by the package under the user-provided basedir: goesdata for storage of downloaded nc files, Scenes to store images composited by GoesCompositor and GoesAnimator, SceneEdits to store edit sessions produced by GoesSceneEditor and Videos to store output videos. For the specific example described above, the tree ends up looking something like this:

.
├── goesdata                            [nc files]
├── SceneEdits                          [Image edits by GoesSceneEditor]   ├── Big_Horn_WY                           ├── Big_Horn_Overlay                 └── Big_Horn_WY_edit1              └── Big_Horn_WY_Fire_Detection             └── Big_Horn_WY_Fire_Edit_1     
├── Scenes                              [Scenes composited by GoesCompositor or GoesAnimator]       ├── Big_Horn_WY                        └── Big_Horn_WY_Fire_Detection
└── Videos                              [Videos generated by GoesAnimator or GoesSceneEditor]
    └── Big_Horn_WY                     
        ├── Big_Horn_Overlay
           └── video.avi
        ├── Big_Horn_WY_Edit1
           └── video.avi
        └── video.avi

The subfolders under Scenes each contain two files, metadata.json and timestamps.csv, that are automatically generated during compositing. For proper functioning of the package, these files should not be altered. In fact, there should be no reason for the user to need to directly alter anything located under the Scenes folder.

There is one additional file needed for the package to function correctly etc/abibands.yaml, which is intended to mirrorabi.yaml found in the Satpy package. This file may need to be manually updated if custom compositors are added to abi.yaml

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

goesvideo-2024.11.5.tar.gz (792.8 kB view details)

Uploaded Source

Built Distribution

goesvideo-2024.11.5-py3-none-any.whl (796.7 kB view details)

Uploaded Python 3

File details

Details for the file goesvideo-2024.11.5.tar.gz.

File metadata

  • Download URL: goesvideo-2024.11.5.tar.gz
  • Upload date:
  • Size: 792.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.0

File hashes

Hashes for goesvideo-2024.11.5.tar.gz
Algorithm Hash digest
SHA256 3fb3b4ac0efe47894d3bf25818eef4e7a0837b8c978c80ac7cd5d06e5b21b5d7
MD5 cf6e24c3184322efd11412880a742621
BLAKE2b-256 982db7634ffd39fd4ce7fc49e16c8a6c1b7383dfaea840a3353f6c2a1bbfe128

See more details on using hashes here.

File details

Details for the file goesvideo-2024.11.5-py3-none-any.whl.

File metadata

File hashes

Hashes for goesvideo-2024.11.5-py3-none-any.whl
Algorithm Hash digest
SHA256 668dfed1570f3a7f9a95be207814b2f1213a50fc072fce1747510ebcef430cba
MD5 de3c64ece47236d1652ed2402dd76c7c
BLAKE2b-256 0d391bf8ad5f61f05e5e06f92e943fc5dc0330ea4e03fd00fc698777389ba6de

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page