ocean-plot

中文 · Downloads · Report a problem

Ocean NetCDF plotting from the command line: SST maps, wind vectors and point time series, powered by xarray.

A small Python CLI for students and researchers who need repeatable figures from rectilinear ocean datasets. Tested with local NOAA OISST and RSS CCMP subsets; includes an offline synthetic demo. It preserves missing values, requires explicit selection of multiple time/depth records, and rejects unsupported grids.

Install and try

Requires Python 3.10+. Use a virtual environment.

python -m pip install "ocean-plot[netcdf4,maps]"
ocean-plot demo --output-dir demo

The demo requires no network or observational data. Its figures are explicitly marked SYNTHETIC — not observations. The package is available on PyPI and GitHub Releases. For the lighter core installation, use python -m pip install ocean-plot.

Development install:

python -m pip install "git+https://github.com/1460197441-web/ocean-plot.git"

The basic installation uses SciPy for NetCDF3. Add netCDF4 for NetCDF4/HDF5 and cartopy for coastlines, or use the extras in the release installation above.

Your own data

ocean-plot inspect input.nc
ocean-plot sst oisst.nc --time-index 0 --bbox 118 126 30 40 --cartopy --output sst.png
ocean-plot wind ccmp.nc --time-index 0 --u uwnd --v vwnd --cartopy --output wind.pdf
ocean-plot timeseries oisst.nc --point 124 35 --output point.png --csv point.csv

• Recognizes common latitude/longitude, SST, and wind variable names; explicit overrides are available.
• Converts known Kelvin units to Celsius and validates geographic wind components in m/s. Arrows show where the wind blows toward, with a reference vector.
• Exports PNG/PDF at 300 dpi and CSV with actual selected coordinates and unrounded numeric values.
• Missing values stay missing. The tool does not interpolate or silently average extra dimensions.

Scope and limitations

Only 1D rectilinear geographic coordinates are supported. Reversed latitude and ordinary 0–360 longitude grids are reordered with their data. Dateline-crossing regional domains that become discontinuous are rejected before plotting; split the input first. A conservative gap check can also reject strongly irregular global grids. Curvilinear, staggered and rotated grids are unsupported.

Default output is a latitude/longitude coordinate plot without a coastline. --cartopy adds Natural Earth 50m coastlines and a visual land overlay; its first use downloads map data. The overlay does not change source values or replace the product's land mask.

Time series use the nearest in-range grid cell and support standard NumPy datetime calendars. NaN observations break the line; entirely absent timestamps do not. No sampling frequency is inferred and no dates are manufactured. See the Chinese reference for full selection and validation rules.

Development and feedback

python -m pip install -e ".[dev,netcdf4]"
pytest
python -m build

CI tests Python 3.10, 3.12 and 3.13. The current suite includes 42 tests covering scientific and CLI regressions.

If it helps your work, a Star or a reproducible issue is welcome. Include dataset/product metadata, coordinate names, units and the exact command; do not upload private data. Contributions are welcome.

MIT applies to the code. External datasets retain their own licenses and attribution requirements.