pyfvcom2.coordinates module

Coordinate transformations for FVCOM model output

pyfvcom2.coordinates.cart2pol(x: ndarray, y: ndarray, degrees: bool = False) → tuple[ndarray, ndarray]

Convert from cartesian to polar coordinates.

Parameters:

  • x – X-coordinates (cartesian). Can be scalar or array-like.

  • y – Y-coordinates (cartesian). Can be scalar or array-like.

  • degrees – If True, return angles in degrees (-180 to 180°), otherwise in radians (-π to π). Defaults to False.

Returns:

  • rho: Radial distances from origin.

  • phi: Angles from positive x-axis. In radians (-π to π) by default,

    or degrees (-180 to 180°) if degrees=True.

Return type:

Tuple containing

Raises:

PyFVCOM2ValueError – If x and y arrays have different shapes.

pyfvcom2.coordinates.get_epsg_code(lon: float, lat: float, datum: str | None = 'WGS 84') → str

Calculate EPSG code from longitude and latitude values.

Parameters:

  • lon (float) – Longitude value.

  • lat (float) – Latitude value.

  • datum (str, optional) – The datum to use. Defaults to “WGS 84”.

Returns:

The EPSG code.

Return type:

str

pyfvcom2.coordinates.lonlat_from_utm(eastings, northings, epsg_code: str)

Convert UTM coordinates to lat/lon.

East Longitudes are positive, west longitudes are negative. North latitudes are positive, south latitudes are negative. Lat and Long are in decimal degrees.

Parameters:

  • eastings (int, float, tuple, list, np.ndarray) – Eastings. Can be single values or array like.

  • northings (int, float, tuple, list, np.ndarray) – Northings. Can be single values or array like.

  • epsg_code (str) – The EPSG code for the utm transformation.

Returns:

A tuple containing:

  • lons (numpy.ndarray): Longitudes for the given eastings and northings.

  • lats (numpy.ndarray): Latitudes for the given eastings and northings.

Return type:

tuple

pyfvcom2.coordinates.pol2cart(rho: ndarray, phi: ndarray, degrees: bool = False) → tuple[ndarray, ndarray]

Convert from polar to cartesian coordinates.

Parameters:

  • rho – Radial distances from origin. Can be scalar or array-like.

  • phi – Angles from positive x-axis. Can be scalar or array-like.

  • degrees – If True, input angles are in degrees, otherwise in radians. Defaults to False.

Returns:

  • x: X-coordinates (cartesian).

  • y: Y-coordinates (cartesian).

Return type:

Tuple containing

Raises:

PyFVCOM2ValueError – If rho and phi arrays have different shapes.

pyfvcom2.coordinates.sigma_to_z_coords(sigma_coords: ndarray, zeta: ndarray, bathymetry: ndarray) → ndarray

Convert sigma to z coordinates.

Parameters:

  • sigma_coords (np.ndarray) – 2D array of sigma coords (n_sigma, n_points).

  • zeta (np.ndarray) – 1D array of zeta values at each horizontal point.

  • bathymetry (np.ndarray) – 1D array of bathymetry values at each horizontal point.

Returns:

2D array of z coordinates (depth levels, horizontal points).

Return type:

np.ndarray

pyfvcom2.coordinates.utm_from_lonlat(longitude, latitude, epsg_code: str | None = None)

Convert lats and lons to UTM coordinates using pyproj.

East Longitudes are positive, west longitudes are negative. North latitudes are positive, south latitudes are negative. Lats and lons are in decimal degrees.

The desired EPSG code can be found by searching websites such as epsg.io or spatialreference.org. If it is not provided, it will be calculated automatically from the first lon and lat values for the WGS 84 datum using the approach described here: https://tinyurl.com/aa83npwy.

Be careful when using this function for coordinates that span multiple zones as the transformation is specific to the specified EPSG reference system.

Parameters:

  • longitude (int, float, tuple, list, np.ndarray) – Longitudes. Can be a single value or array like.

  • latitude (int, float, tuple, list, np.ndarray) – Latitudes. Can be a single value or array like.

  • epsg_code (str, optional) – The EPSG code for the utm transformation.

Returns:

A tuple containing:

  • eastings (numpy.ndarray): Eastings in the supplied reference system.

  • northings (numpy.ndarray): Northings in the supplied reference system.

  • epsg_code (str): The EPSG code for the utm transformation.

Return type:

tuple

pyfvcom2.coordinates.z_to_sigma_coords(z_coords: ndarray, zeta: ndarray, bathymetry: ndarray) → ndarray

Convert z to sigma coordinates.

Parameters:

  • z_coords (np.ndarray) – 2D array of z coords (n_levels, n_points).

  • zeta (np.ndarray) – 1D array of zeta values at each horizontal point.

  • bathymetry (np.ndarray) – 1D array of bathymetry values at each horizontal point.

Returns:

2D array of sigma coordinates (n_levels, n_points).

Return type:

np.ndarray