aruco_tool

Library for using ARuCo tags.

Installation

Dependencies

Highly recommend installing these packages separately before pip installing this package.

• pandas
• numpy
• opencv-contrib-python
• matplotlib

Install with Pip

For now, package is on testpypi. Install using this command: pip install -i https://test.pypi.org/simple/ aruco-tool

Quick-Start Guide

Aruco detects corners of the code, then converts that to pose. Right now, the pose is calculated relatively, as a differential from the first pose detected of the id. Please see our documentation and the aruco documentation for more details.

Will update this with more analysis modes in the future.

Note: OpenCV doesn't work well with python pathlib, for now we also don't handle pathlib Paths. Please make sure to convert your paths to str, if you are using pathlib. Otherwise, please provide the absolute path for your files.

Finding corners

    from aruco_tool import CornerFinder

    # set up for aruco analysis
    aruco_dict = aruco.getPredefinedDictionary(aruco.DICT_4X4_250) # or another dictionary
    aruco_params = aruco.DetectorParameters_create()

    # see note above
    folder = str( Path(__file__).parent.resolve() / "folder/location" )

    cf = CornerFinder(folder, ar_dict=aruco_dict, ar_params=aruco_params, data_name="optional label", desired_ids=None)
    ids_found = cf.corner_analysis()

Corner location data is stored as numpy arrays in an ArucoCorner object. There is one ArucoCorner object generated for each aruco code found and these are stored in a dictionary, which is the output of cf.corner_analysis, with the id as the key.

    # grabs ArucoCorner obj with id of 0
    ac = ids_found[0]

    ac.id  # stores the aruco id number
    ac.folder_loc # stores where the data was collected
    ac.corners # numpy array of corners found
    df = ac.gen_corners_df() # generates a pandas dataframe of the corners

Converting corner data to pose data

Remember to get your camera matrix and dist coeffs from camera calibration.

    from aruco_tool import PoseDetector

    pdetect = PoseDetector(ac (ArucoCorner obj), opencv-camera-matrix, opencv_dist_coeffs, marker_side_dimensions (float), processing_freq (float, not-used))

    # Poses are returned in the form of ArucoLoc objects
    aloc = pdetect.find_marker_locations()

Pose data is stored as numpy arrays in an ArucoLoc object for a single id. Repeat this process for each ArucoCorner object you get from the CornerFinder.

    aloc.id  # stores the aruco id number
    aloc.folder_loc  # stores where the data was collected
    aloc.poses  # numpy array of poses: [x, y, z, magnitude of translation, roll, pitch, yaw, relative magnitude of rotation] -> all relative from initial image
    aloc.gen_poses_df()  # generates a pandas dataframe of the corners

Stream-lined process

Aruco_tool also provides simple, one-line functions for aruco analysis, located in the ArucoFunc object. The functions above are mainly designed for sets of images, however these functions provide the ability to selectively run on one image.

    from aruco_tool import ArucoFunc
    af = ArucoFunc(opencv-camera-calibration, opencv_radial_and_tangential_dists, marker_side_dimensions (float))  # stores analysis variables, by default provides my attributes

    # see note above
    file = str( Path(__file__).parent.resolve() / "file_location.jpg" )
    folder = str( Path(__file__).parent.resolve() / "folder/location" )
    
    # run on a single image with one id to track
    pose_array = af.single_image_analysis_single_id(file, desired_id_num)

    # run on a set of images with one id to track
    aruco_loc = af.full_analysis_single_id(folder, desired_id_num)

    # run on a single image, track multiple ids or grab all ids in img
    set_of_aruco_locs = af.single_image_analysis(file, desired_ids=None (list)) # if none, grabs all ids in image, otherwise you can specify using a list

    # run on a set of images, track multiple ids or grab all ids in imgs
    set_of_aruco_locs = af.full_analysis(folder, desired_ids=None (list))

Extra Helper Functions

Aruco_tool also provides extra functions for visualization and debugging. These functions can be imported directly.

    from aruco_tool import load_corners, load_poses, show_image

    # see note above
    id_num = 3
    file = str( Path(__file__).parent.resolve() / "file_location.csv" )
    img_file = str( Path(__file__).parent.resolve() / "file_location.jpg" )

    a_corner_obj = load_corners(file, id_num)
    a_loc_obj = load_poses(file, id_num)  # loads csv of pose data into an ArucoLoc object
    show_image(img_file, include_corners (bool), marker_size (float))  # shows an image, can choose to show detected corners on the image with the indicated marker size