# Geometry

group `harp_geometry`

  The HARP Geometry module contains public functions for dealing with polygons and points on a spherical surface.

  Functions

  int `harp_geometry_get_point_distance`(double latitude_a, double longitude_a, double latitude_b, double longitude_b, double *distance)

    Calculate the distance between two points on the surface of the Earth in meters

    This function assumes a spherical earth

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `latitude_a`: Latitude of first point
      - `longitude_a`: Longitude of first point
      - `latitude_b`: Latitude of second point
      - `longitude_b`: Longitude of second point
      - `distance`: Pointer to the C variable where the surface distance in [m] between the two points will be stored.
  int `harp_geometry_has_point_in_area`(double latitude_point, double longitude_point, int num_vertices, double *latitude_bounds, double *longitude_bounds, int *in_area)

    Determine whether a point is in an area on the surface of the Earth

    This function assumes a spherical earth.

    The latitude/longitude bounds can be either vertices of a polygon (num_vertices>=3) or represent corner points that define a bounding rect (num_vertices==2).

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `latitude_point`: Latitude of the point
      - `longitude_point`: Longitude of the point
      - `num_vertices`: The number of vertices of the bounding polygon/rect of the area
      - `latitude_bounds`: Latitude values of the bounds of the area polygon/rect
      - `longitude_bounds`: Longitude values of the bounds of the area polygon/rect
      - `in_area`: Pointer to the C variable where the result will be stored (1 if point is in the area, 0 otherwise).
  int `harp_geometry_has_area_overlap`(int num_vertices_a, double *latitude_bounds_a, double *longitude_bounds_a, int num_vertices_b, double *latitude_bounds_b, double *longitude_bounds_b, int *has_overlap, double *fraction)

    Determine whether a point is in an area on the surface of the Earth

    This function assumes a spherical earth. The overlap fraction is calculated as area(intersection)/min(area(A),area(B)).

    The latitude/longitude bounds for A and B can be either vertices of a polygon (num_vertices>=3), or represent corner points that define a bounding rect (num_vertices==2).

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `num_vertices_a`: The number of vertices of the bounding polygon/rect of the first area
      - `latitude_bounds_a`: Latitude values of the bounds of the area of the first polygon/rect
      - `longitude_bounds_a`: Longitude values of the bounds of the area of the first polygon/rect
      - `num_vertices_b`: The number of vertices of the bounding polygon/rect of the second area
      - `latitude_bounds_b`: Latitude values of the bounds of the area of the second polygon/rect
      - `longitude_bounds_b`: Longitude values of the bounds of the area of the second polygon/rect
      - `has_overlap`: Pointer to the C variable where the result will be stored (1 if there is overlap, 0 otherwise).
      - `fraction`: Pointer to the C variable where the overlap fraction will be stored (use NULL if not needed).
  int `harp_geometry_get_area`(int num_vertices, double *latitude_bounds, double *longitude_bounds, double *area)

    Calculate the area size for a polygon on the surface of the Earth

    This function assumes a spherical earth.

    The latitude/longitude bounds for A and B can be either vertices of a polygon (num_vertices>=3), or represent corner points that define a bounding rect (num_vertices==2).

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `num_vertices`: The number of vertices of the bounding polygon/rect
      - `latitude_bounds`: Latitude values of the bounds of the polygon/rect
      - `longitude_bounds`: Longitude values of the bounds of the polygon/rect
      - `area`: Pointer to the C variable where the area size will be stored (in [m2]).