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.

Args:

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:

Tuple containing:

• rho: Radial distances from origin.

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

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

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.

Args:

lon (float): Longitude value. lat (float): Latitude value. datum (str, optional): The datum to use. Defaults to “WGS 84”.

Returns:

str: The EPSG code.

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.

Args:

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:

tuple: A tuple containing:

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

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

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

Convert from polar to cartesian coordinates.

Args:

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:

Tuple containing:

• x: X-coordinates (cartesian).

• y: Y-coordinates (cartesian).

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.

Args:

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:

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

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.

Args:

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:

tuple: 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.

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

Convert z to sigma coordinates.

Args:

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:

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