Classes

AcTag

class actag.AcTag(min_range: float, max_range: float, horizontal_aperture: float, tag_family: str, tag_size: float, median_filter_kernel_radius: int = 4, adaptive_threshold_kernel_radius: int = 8, adaptive_threshold_offset: float = 1, contours_tag_size_tolerance: float = 0.2, contours_tag_area_tolerance: float = 0.2, contours_min_tag_area_ratio: float = 0.1, contours_reject_black_shapes: bool = True, contours_reject_white_shapes: bool = False, contours_reject_by_tag_size: bool = True, contours_reject_by_area: bool = True, quads_random_seed: int | None = None, quads_points_per_line_ratio: float = 0.1, quads_dist_for_inlier: float = 2.5, quads_desired_inlier_ratio: float = 0.85, quads_required_inlier_ratio: float = 0.8, quads_parallel_threshold: float = 0.9, quads_use_same_random_vals: bool = False, quads_starting_roll_val: int = 123456, decoding_num_bit_corrections: int = 4, use_optimized_rust_code: bool = True)

Class for detecting AcTags in sonar images.

Parameters:

  • min_range (float) – The minimum range setting on the sonar used to capture this image.

  • max_range (float) – The maximum range setting on the sonar used to capture this image.

  • horizontal_aperature (float) – The horizontal aperature setting (in radians) on the sonar used to capture this image.

  • vertical_aperature (float) – The vertical aperature setting (in radians) on the sonar used to capture this image.

  • tag_family (str) – The name of a AcTag family found in the actag_families/generated_families folder, or the path to a valid AcTag family file. See the actag_families module for more information.

  • tag_size (float) – The length of the inner square of white data bits in meters.

  • median_filter_kernel_radius (int) – The neighborhood radius for the median filter.

  • adaptive_threshold_kernel_radius (int) – The neighborhood radius for the adaptive threshold.

  • adaptive_threshold_offset (float) – The offset value for the adaptive threshold.

  • contours_tag_size_tolerance (float) – The error tolerance for contours bigger than the tag_size. Contours with an x or y length longer than tag_size * (1 + contours_tag_size_tolerance) will be rejected.

  • contours_tag_area_tolerance (float) – The error tolerance for contours outside the range of expected tag areas. Contours with an area outside of the tolerances will be rejected.

  • contours_min_tag_area_ratio (float) – The minimum expected tag area, as max_expected_area * contours_min_tag_area_ratio.

  • contours_reject_black_shapes (bool) – Determines whether the contour rejection algorithm should reject edges that contours that go from white to black. When true, this will reject contours that can’t be the inner quadrilateral of an AcTag.

  • contours_reject_white_shapes (bool) – Determines whether the contour rejection algorithm should reject edges that contours that go from black to white. When false, this won’t reject contours that can be the inner quadrilateral of an AcTag.

  • contours_reject_by_tag_size (bool) – If true, will reject contours outside of the tag_size error tolerances.

  • contours_reject_by_area (bool) – If true, will reject contours outside of the tag area error tolerances.

  • quads_random_seed (int or None) – If specified, the discrete uniform random number generator will be seeded with this value. If not specified, the random number generator will have a random seed, leading to new values each time it is run.

  • quads_points_per_line_ratio (float) – The ratio of the number of points within a contour to use for each line fit.

  • quads_dist_for_inlier (float) – The distance threshold for a point to be considered an inlier.

  • quads_desired_inlier_ratio (float) – The desired ratio of inliers within the total number of points.

  • quads_required_inlier_ratio (float) – The required ratio of inliers within the total number of points to successfully fit a quadrilateral.

  • quads_parallel_threshold (float) – Value used for determining whether or not two lines are parallel, when checking if the quad is a parallelogram.

  • quads_use_same_random_vals (bool) – Set to true to use repeatable random values, starting with the starting_roll_val. Used to syncronize random values between Python & Rust versions of the code (for testing purposes).

  • quads_starting_roll_val (int) – The starting roll value used for when quads_use_same_random_vals is set to True.

  • decoding_num_bit_corrections (int) – The number of bit corrections allowed during the coding process. THis value must be greater than 0 and less than half of the minimum hamming distance of the AcTag family.

  • use_optimized_rust_code (bool) – If true, will use the optimized Rust code, which runs significantly faster. If false, will use the Python code.

Raises:

ValueError – Raised if decoding_num_bit_corrections is less than 0 or greater than/equal to half of the hamming distance of the Actag family.

run_detection(sonar_img: ndarray) → list[list[int, ndarray, ndarray]]

Runs the full detection algorithm on the given sonar image.

Steps:

  1. Filter the image with a Median filter.

  2. Binarize the image with an adaptive threshold.

  3. Find contours in the image.

  4. Fit quadrilaterals to the contours.

  5. Decode the tags.

Parameters:

sonar_img (np.ndarray) – The sonar image. The first row, last row, first column, and last column of the image should correspond with the maximum range, minimum range, maximum azimuth, and minimum azimuth of the sonar, respectively.

Returns:

The list of detected tags. Each detected tag is a list of the form `[tag_id, corner_indices, range_and_azimuth_values]`. `tag_id` is an integer value indicating the tag ID in the specified tag family. `corner_indices` is a 2D numpy array containing `[row, column]` pairs for each of the four corners of the tag. The top-left tag corner is first, followed by the top-right, and around in a clockwise fashion. Note that “top-left” refers to the corner in the top-left of the AcTag’s image file, not the corner which happens to appear in the top-left of the current sonar image. `range_and_azimuth_values` is a 2D numpy array with `[range, azimuth]` pairs (in meters and radians, respectively) corresponding to each of the four corners, in the same order as `corner_indices`.

Return type:

list[list[int, np.ndarray, np.ndarray]]

visualize_detection(sonar_img: ndarray) → list[list[int, ndarray, ndarray]]

Same as run_detection(), but also visualizes each step of the process using matplotlib.

Parameters:

sonar_img (np.ndarray) – The sonar image. The first row, last row, first column, and last column of the image should correspond with the maximum range, minimum range, maximum azimuth, and minimum azimuth of the sonar, respectively.

Returns:

The list of detected tags. Each detected tag is a list of the form `[tag_id, corner_indices, range_and_azimuth_values]`. `tag_id` is an integer value indicating the tag ID in the specified tag family. `corner_indices` is a 2D numpy array containing `[row, column]` pairs for each of the four corners of the tag. The top-left tag corner is first, followed by the top-right, and around in a clockwise fashion. Note that “top-left” refers to the corner in the top-left of the AcTag’s image file, not the corner which happens to appear in the top-left of the current sonar image. `range_and_azimuth_values` is a 2D numpy array with `[range, azimuth]` pairs (in meters and radians, respectively) corresponding to each of the four corners, in the same order as `corner_indices`.

Return type:

list[list[int, np.ndarray, np.ndarray]]

SonarParams

class actag.sonar_parameters.SonarParams(min_range: float, max_range: float, horizontal_aperture: float)

Class that contains the parameters of the sonar.

Parameters:

  • min_range (float) – Minimum range of the sonar in meters.

  • max_range (float) – Maximum range of the sonar in meters.

  • horizontal_aperture (float) – Horizontal aperture of the sonar in radians.

AcTagParams

class actag.tag_parameters.AcTagParams(tag_family: str, tag_size: float)

Stores the parameters of an AcTag family. It also finds the the tag family file and parses the data into memory.

Parameters:

  • tag_family (str) – The name of a AcTag family found in the actag_families/generated_families folder, or the path to a valid AcTag family file. See the actag_families module for more information.

  • tag_size (float) – The length of the inner white square of the physical AcTag used in meters.

get_tags_in_family(file_path: str) → list[list]

This function parses the data from the AcTag family file and returns a list containing the data bit layouts for each tag in the family.

Parameters:

file_path (str) – The path to the AcTag family file.

Returns:

A list containing the data bit layouts for each tag in the family, including rotations and reversals.

Return type:

list[list]