{"id":17334258,"url":"https://github.com/cmower/aruco_markers","last_synced_at":"2025-07-01T13:07:22.714Z","repository":{"id":150113841,"uuid":"618563641","full_name":"cmower/aruco_markers","owner":"cmower","description":"A compact Python package for handling ArUCo markers.","archived":false,"fork":false,"pushed_at":"2023-04-21T10:29:54.000Z","size":843,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-01T13:07:09.098Z","etag":null,"topics":["aruco-markers","computer-vision","object-pose-estimation","opencv-python","python","state-estimation"],"latest_commit_sha":null,"homepage":"https://cmower.github.io/aruco_markers/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmower.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-24T18:40:29.000Z","updated_at":"2025-06-03T12:06:51.000Z","dependencies_parsed_at":"2024-11-08T06:03:51.925Z","dependency_job_id":"1e2363c7-75da-4f64-a751-209a0799f343","html_url":"https://github.com/cmower/aruco_markers","commit_stats":{"total_commits":53,"total_committers":4,"mean_commits":13.25,"dds":"0.16981132075471694","last_synced_commit":"40f341b9fc70831d5832ccf5937a05c708ae3ae3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cmower/aruco_markers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmower%2Faruco_markers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmower%2Faruco_markers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmower%2Faruco_markers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmower%2Faruco_markers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmower","download_url":"https://codeload.github.com/cmower/aruco_markers/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmower%2Faruco_markers/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262969883,"owners_count":23392529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aruco-markers","computer-vision","object-pose-estimation","opencv-python","python","state-estimation"],"created_at":"2024-10-15T15:05:33.696Z","updated_at":"2025-07-01T13:07:22.685Z","avatar_url":"https://github.com/cmower.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cmower/aruco_markers/master/doc/image/marker.png\" width=\"60\" align=\"right\"\u003e\n\u003c/p\u003e\n\n# aruco_markers\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nThe `aruco_markers` package is a compact Python toolkit designed to manage ArUCo markers.\nIt serves as a streamlined interface for the OpenCV aruco module and offers a range of capabilities through both a command line interface and a simplified library interface.\nFor more information, refer to the accompanying documentation.\n\n* Code: [https://github.com/cmower/aruco_markers](https://github.com/cmower/aruco_markers)\n* Documentation: [https://cmower.github.io/aruco_markers/](https://cmower.github.io/aruco_markers/)\n* PyPI: [https://pypi.org/project/aruco-markers/](https://pypi.org/project/aruco-markers/)\n* Issues: [https://github.com/cmower/aruco_markers/issues](https://github.com/cmower/aruco_markers/issues)\n\n# Install\n\n## From PyPI\n\n```\npip install aruco_markers\n```\n\n## From source\n\nIn a new terminal:\n1. Clone repository:\n   - (ssh) `$ git clone git@github.com:cmower/aruco_markers.git`, or\n   - (https) `$ git clone https://github.com/cmower/aruco_markers.git`\n2. Change directory: `$ cd aruco_markers`\n3. Ensure `pip` is up-to-date: `$ python -m pip install --upgrade pip`\n3. Install from source: `$ pip install .`\n\n# The `aruco_markers` library\n\nAll the functionality of the library can be accessed via\n\n```python\nimport aruco_markers\n```\n\nFull documentation for all the classes/functions provided can be found [here](https://cmower.github.io/aruco_markers/).\n\n# Command line interface\n\nSeveral features of the library are exposed to the command line via the `aruco` command.\nWhen running these commands, several directories will be created.\nThe top level directory is `~/aruco_markers_data`.\nAll the data created by these commands are stored here, specified in the following sub-sections.\n\nThe available commands are\n* `collect`: Collect data with checkerboard to calibrate a camera.\n* `calibrate`: Calibrate a camera.\n* `generate`: Generate marker tags.\n* `detect`: Detect marker poses from camera feed.\n* `server`: Start a camera server.\n\nThe use of these commands are described below.\nIn addition, you can access the documentation for ecah command by appending `--help`.\nFor example\n```\n$ aruco generate --help\nusage: aruco generate [OPTIONS]\n\nGenerate marker tags.\n\noptional arguments:\n  -h, --help            Show this help message and exit.\n  -d DICT, --dict DICT  The dictionary for the ArUCo marker. The default is 'DICT_ARUCO_ORIGINAL'.\n  -i ID, --id ID        Identifier of the marker. It has to be a valid id in the specified dictionary. The default is '100'.\n  -s SIDEPIXELS, --sidepixels SIDEPIXELS\n                        Size of the ArUCo tag. The default is '200'.\n  -w WIDTH, --width WIDTH\n                        Width of the marker in millimeters. The default is '50'.\n  -p PAD, --pad PAD     Padding around marker in millimeters. The image is positioned on an A4 pdf. The default is '20'.\n  -l LABEL, --label LABEL\n                        Add an optional label to the marker. The default is ''.\n  --noshow              Display the marker. If unspecified the tag is shown.\n  --save                Save the marker. Tags are saved in ~/aruco_markers/tags; this directory is created when it does not already exist.\n  --addhalfmarks        Add marks at the half-way marks on the pdf. If unspecified no marks are added.\n```\n\nSimilarly for each of the other commands.\n\n## Generating markers\n\nYou can generate markers using the `aruco generate` command.\nWhen the `--save` flag is included in the command line input, the marker data is saved in the `~/aruco_markers_data/tags` directory.\nTwo files are created, an image of the marker as a PNG and a printable PDF.\nThe PDF includes the tag and meta information as human-readable text.\n\nFor example, try running\n```\n$ aruco generate --dict DICT_ARUCO_ORIGINAL --id 100 --save --noshow\n```\n\nThe expected output is as follows (note `HOMEDIR` will be relaced with what ever your home directory is set as).\n\n```\nCreated HOMEDIR/aruco_markers_data\nCreated HOMEDIR/aruco_markers_data/tags\nSaved\n  HOMEDIR/aruco_markers_data/tags/marker_dict_DICT_ARUCO_ORIGINAL_id_100_sidepixels_200_borderbits_1_width_500_pad_20.png\n  HOMEDIR/aruco_markers_data/tags/marker_dict_DICT_ARUCO_ORIGINAL_id_100_sidepixels_200_borderbits_1_width_500_pad_20.pdf\n```\n\n*Note*, if you have already run `aruco generate` before, then it is possible you will not see the lines acknowledging a directories creation (i.e. those starting with `Created`).\n\nThe PNG file created should match the marker displayed at the top of this readme, i.e. [here](https://cmower.github.io/aruco_markers/marker.png).\n\nThe full list of available dictionaries are as follows.\n\n* DICT_4X4_50\n* DICT_4X4_100\n* DICT_4X4_250\n* DICT_4X4_1000\n* DICT_5X5_50\n* DICT_5X5_100\n* DICT_5X5_250\n* DICT_5X5_1000\n* DICT_6X6_50\n* DICT_6X6_100\n* DICT_6X6_250\n* DICT_6X6_1000\n* DICT_7X7_50\n* DICT_7X7_100\n* DICT_7X7_250\n* DICT_7X7_1000\n* DICT_ARUCO_ORIGINAL\n* DICT_APRILTAG_16h5\n* DICT_APRILTAG_25h9\n* DICT_APRILTAG_36h10\n* DICT_APRILTAG_36h11\n\nWhen creating markers, it's often the case you want to affix the printed marker onto an object.\nIn such cases, knowing the mid-points of the rectangle is helpful, as manual measurements can be inaccurate.\nTo simplify this process, you can use the `--addhalfmarks` flag in the `aruco generate` command while generating markers.\nThe following is an example of how the output would look like when running this command.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cmower/aruco_markers/master/doc/image/marker-with-mark.png\" width=\"60%\" align=\"center\"\u003e\n\u003c/p\u003e\n\n## Calibrating a camera\n\nCalibrating a camera can be performed using the `aruco collect` and  `aruco calibrate` command.\nRunning this command will take you through several steps in order to calibrate the camera.\n\n### Prerequisites\n\nYou will require a checkerboard to complete the calibration process.\nA good resource for getting printable checkerboards can be found [here](https://markhedleyjones.com/projects/calibration-checkerboard-collection).\nIt is a good idea to attach the printed checkerboard to a flat surface.\n\nYou can also find a checkerboard in the `doc/` directory called `Checkerboard-A4-25mm-8x6.pdf`.\nThis is a 8-by-6 checkerboard, where each square has length 25mm when printed on A4.\n\n### Collect data\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cmower/aruco_markers/master/doc/image/checkerboard.png\" width=\"60%\" align=\"center\"\u003e\n\u003c/p\u003e\n\nTo gather data for calibration, execute the `aruco collect` command.\nWhen the checkerboard is detected correctly, a result similar to the one depicted in the above figure should appear.\nPress the ESC key to stop collecting data.\n\nTo obtain accurate estimated parameters from the calibration process, it is advisable to move the checkerboard to different depths and orientations on the screen.\nKeep in mind that a considerable amount of data could be collected, so make sure that your PC has sufficient storage capacity.\nThe quantity of data required is uncertain, but collecting more data will generally result in more precise estimated parameters.\nNevertheless, processing more data will take more time.\nEnsuring sufficient coverage of depths and orientations is important.\n\nIn this particular example, I used the `Checkerboard-A4-25mm-8x6.pdf` found in the `doc/` directory for the checkerboard.\nSince I am using my laptop's webcam, the camera index is `0` (which is the default value).\nI began the data collection process by executing the following command.\n\n```\n$ aruco collect --width 8 --height 6 --squaresize 25\n```\n\nRun `$ aruco collect --help` if you need more clarity on the command line input variables.\n\nYou should expect terminal output similar to the following.\n\n```\n$ aruco collect --width 8 --height 6 --squaresize 25\nPress ESC to quit.\nCreated HOMEDIR/aruco_markers_data\nCreated HOMEDIR/aruco_markers_data/calibrate\nCreated HOMEDIR/aruco_markers_data/calibrate/CAMERANAME\nData collection completed for the 'CAMERANAME' camera.\nData saved in HOMEDIR/aruco_markers_data/calibrate/CAMERANAME\n```\n\nIn the above, `HOMEDIR` is your home directory, i.e. where ever `~/` is on you PC, and `CAMERANAME` is the camera name used for data collection.\nThis should correspond to the camera you intend to calibrate (if you have more than one camera attached to your PC).\nNote the `CAMERANAME`, it will be required in the calibration step next.\n\nAll the raw images that contain the checkerboard are collected into a zip file called `data.zip`.\nYou can run the collection process several times, and the new data is appended to the zip file (the collection *does not* overwrite previously collected data).\n\n### Calibrate camera\n\nOnce you have collected data (as described in the previous section), you can directly perform the calibration.\nAll you require is the name of the camera (this was ouput to the terminal during the data collection, see `CAMERANAME` in previous section).\n\nIn my example, I ran the following.\n\n```\n$ aruco calibrate --cameraname CAMERANAME\n```\n\nThe terminal output should look similar to the following.\n\n```\n$ aruco calibrate --cameraname CAMERANAME\nProcessing checkerboard images ...\nLoaded (1/60) checkerboard_cameraname_CAMERANAME_width_8_height_6_squaresize_25.0_stamp_UNIQUETIMESTAMP.png\n  Processing ... success!\n\n...\n\nLoaded (60/60) checkerboard_cameraname_CAMERANAME_width_8_height_6_squaresize_25.0_stamp_UNIQUETIMESTAMP.png\n  Processing ... success!\nDone!\nCalibrating camera ... done!\nCalibration took 1.0067 seconds\nCamera matrix:\n [[617.49438628   0.         318.25186084]\n [  0.         617.0481798  263.17630606]\n [  0.           0.           1.        ]]\n\nDistorion Cooeficients:\n [[-3.22848626e-01  2.43430897e+00 -2.73404118e-04  3.06017375e-03\n  -7.64518705e+00]]\nSaved HOMEDIR/aruco_markers_data/calibrate/CAMERANAME/camera_parameters.dat\nCompleted calibration successfully.\n```\n\nIn the above, 60 files were successfully processed.\n*Note*, each file name is given a unique time stamp so files are not overwritten.\nThe duration of the calibration process is reported and also the estimated parameters.\nYou do not need to note these since they are saved in the `camera_parameters.dat` file.\n\nIf you have a lot of data and the processing is taking too long, you can downsample the data by specifying the `--maxfiles MAXFILES` flag.\nThis will randomly sample `MAXFILES` files from the file names (uniform distribution) and then perform the calibration.\n\n## View pose detection from a camera feed\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cmower/aruco_markers/master/doc/image/marker_ex.png\" width=\"60%\" align=\"center\"\u003e\n\u003c/p\u003e\n\nAfter calibrating a camera, you can use the `aruco detect` command to display the position of a marker.\nThis function is primarily intended for debugging and serves as a demonstration of detector configuration.\nHowever, if the camera has not been calibrated beforehand, this command will throw an error.\n\nWhen you run `aruco detect` you should see something similar to the figure above.\nI ran this example by running the following in terminal.\n\n```\n$ aruco detect --dict DICT_4X4_50 --markerindex 0\n```\n\n*Note*, the marker I use in this example has a length of 5cm.\nThis information is required if you want to use the pose estimation.\n\n## Server\n\nYou can run a server that will broadcast images to a UDP network.\nSimply run the following\n\n```\n$ aruco server\n```\n\nSeveral listeners can recieve the feeds from this server.\nThe information flow is as follows.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cmower/aruco_markers/master/doc/image/server-overview.png\" width=\"60%\" align=\"center\"\u003e\n\u003c/p\u003e\n\nTo see this in action try running the example script [example/server_listener.py](https://github.com/cmower/aruco_markers/blob/master/example/server_listener.py).\n**Note**, this script can be run multiple times in separate terminals.\n\n# Marker pose estimation\n\nIf you opt for the `aruco_markers` package, you can use the command line interface to produce tags and calibrate cameras.\nHowever, if you require additional features, you can customize the class/method structure available in the library.\nSeveral methods are provided to that enable you to easily load camera parameters, and estimate marker poses.\n\nPlease see the examples, that show how to implement a simple pose estimator into [ROS 1](example/ros1_tf_publisher.py)/[ROS 2](example/ros2_tf_publisher.py).\nThis example assumes you have calibrated your camera by running `aruco collect`, and `aruco calibrate` prior to running this script.\n\n# Build documentation\n\nThe documentation is hosted [here](https://cmower.github.io/aruco_markers/).\nHowever, if you would like to build the documentation yourself, follow these steps.\n\nIn a new terminal:\n1. Clone repository:\n   - (ssh) `$ git clone git@github.com:cmower/aruco_markers.git`, or\n   - (https) `$ git clone https://github.com/cmower/aruco_markers.git`\n2. Change directory: `$ cd aruco_markers/doc`\n3. Generate the main page: `$ python gen_mainpage.py`\n3. Install doxygen: `$ sudo apt install doxygen`\n4. Build documentation: `$ doxygen`\n5. View documentation:\n   - In a browser, open `html/index.html`\n   - Build pdf (requires LaTeX)\n\t - `$ cd latex`\n\t - `$ make`\n\t - Open the file called `refman.pdf`\n\n# Supported cameras\n\nGenerally, any camera that is accessible by the OpenCV `VideoCapture` class is supported.\nOthers include\n\n* The [ZED-Mini](https://www.stereolabs.com/zed-mini/) RGBD camera.\n\n# Citing\n\nIf you use `aruco_markers` in your work, please consider citing the following.\n\n```bibtex\n@software{Mower2023\n  title = \"aruco_markers: A Compact Python Package for handling ArUCo markers\",\n  author = \"Christopher E. Mower\",\n  year = \"2023\",\n  url = {https://github.com/cmower/aruco_markers},\n}\n```\n\n# Contributing\n\nIf you have any issues with the library, or find inaccuracies in the documentation please [raise an issue](https://github.com/cmower/aruco_markers/issues/new/choose).\nI am happy to consider new features if you [fork the library](https://github.com/cmower/aruco_markers/fork) and submit a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmower%2Faruco_markers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmower%2Faruco_markers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmower%2Faruco_markers/lists"}