aruco-pose 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aruco-pose-0.2.0/CONTRIBUTING.md +119 -0
- aruco-pose-0.2.0/LICENSE +201 -0
- aruco-pose-0.2.0/MANIFEST.in +9 -0
- aruco-pose-0.2.0/PKG-INFO +226 -0
- aruco-pose-0.2.0/README.md +199 -0
- aruco-pose-0.2.0/aruco_pose/__init__.py +26 -0
- aruco-pose-0.2.0/aruco_pose/__main__.py +6 -0
- aruco-pose-0.2.0/aruco_pose/cli.py +403 -0
- aruco-pose-0.2.0/aruco_pose/core/__init__.py +7 -0
- aruco-pose-0.2.0/aruco_pose/core/detector.py +191 -0
- aruco-pose-0.2.0/aruco_pose/kit_cli.py +150 -0
- aruco-pose-0.2.0/aruco_pose/models/__init__.py +18 -0
- aruco-pose-0.2.0/aruco_pose/models/aruco_pose_estimator.py +109 -0
- aruco-pose-0.2.0/aruco_pose/models/aruco_pose_pipeline.py +90 -0
- aruco-pose-0.2.0/aruco_pose/models/dodecahedron_model.py +196 -0
- aruco-pose-0.2.0/aruco_pose/pose.py +702 -0
- aruco-pose-0.2.0/aruco_pose/starter.py +393 -0
- aruco-pose-0.2.0/aruco_pose/starter_sample.py +78 -0
- aruco-pose-0.2.0/aruco_pose/tracking/__init__.py +7 -0
- aruco-pose-0.2.0/aruco_pose/tracking/dense_refinement.py +165 -0
- aruco-pose-0.2.0/aruco_pose/tracking/optical_flow.py +15 -0
- aruco-pose-0.2.0/aruco_pose/tracking/pose_refiner.py +23 -0
- aruco-pose-0.2.0/aruco_pose/tracking/predictive_filter.py +30 -0
- aruco-pose-0.2.0/aruco_pose/utils/__init__.py +19 -0
- aruco-pose-0.2.0/aruco_pose/utils/config.py +199 -0
- aruco-pose-0.2.0/aruco_pose/utils/dodecahedron_overlay.py +19 -0
- aruco-pose-0.2.0/aruco_pose/utils/io.py +296 -0
- aruco-pose-0.2.0/aruco_pose/utils/legacy_utils.py +445 -0
- aruco-pose-0.2.0/aruco_pose/utils/logger.py +80 -0
- aruco-pose-0.2.0/aruco_pose/utils/marker_generator.py +192 -0
- aruco-pose-0.2.0/aruco_pose/utils/performance.py +228 -0
- aruco-pose-0.2.0/aruco_pose/utils/visualization.py +276 -0
- aruco-pose-0.2.0/aruco_pose.egg-info/PKG-INFO +226 -0
- aruco-pose-0.2.0/aruco_pose.egg-info/SOURCES.txt +100 -0
- aruco-pose-0.2.0/aruco_pose.egg-info/dependency_links.txt +1 -0
- aruco-pose-0.2.0/aruco_pose.egg-info/entry_points.txt +3 -0
- aruco-pose-0.2.0/aruco_pose.egg-info/requires.txt +18 -0
- aruco-pose-0.2.0/aruco_pose.egg-info/top_level.txt +1 -0
- aruco-pose-0.2.0/assets/starter/board.json +110 -0
- aruco-pose-0.2.0/assets/starter/calibration.mp4 +0 -0
- aruco-pose-0.2.0/assets/starter/checkerboard.svg +40 -0
- aruco-pose-0.2.0/assets/starter/ground_truth.csv +121 -0
- aruco-pose-0.2.0/assets/starter/marker_board.svg +151 -0
- aruco-pose-0.2.0/assets/starter/reference_camera.json +29 -0
- aruco-pose-0.2.0/assets/starter/sample_info.json +18 -0
- aruco-pose-0.2.0/assets/starter/tracking.mp4 +0 -0
- aruco-pose-0.2.0/config/aruco_group.json +138 -0
- aruco-pose-0.2.0/config/dodecahedron_face_map.json +374 -0
- aruco-pose-0.2.0/config/dodecahedron_with_markers.json +534 -0
- aruco-pose-0.2.0/docs/MODEL_SCALING.md +56 -0
- aruco-pose-0.2.0/docs/PACKAGE_MIGRATION.md +60 -0
- aruco-pose-0.2.0/docs/POSE_API.md +219 -0
- aruco-pose-0.2.0/docs/PUBLISHING.md +64 -0
- aruco-pose-0.2.0/docs/ROADMAP.md +123 -0
- aruco-pose-0.2.0/examples/01_basic/README.md +128 -0
- aruco-pose-0.2.0/examples/01_basic/basic_detection.py +67 -0
- aruco-pose-0.2.0/examples/01_basic/camera_calibration.py +62 -0
- aruco-pose-0.2.0/examples/01_basic/config_example.py +124 -0
- aruco-pose-0.2.0/examples/01_basic/generate_markers.py +54 -0
- aruco-pose-0.2.0/examples/02_single_marker/README.md +182 -0
- aruco-pose-0.2.0/examples/02_single_marker/marker_tracking.py +37 -0
- aruco-pose-0.2.0/examples/02_single_marker/pose_estimation_demo.py +117 -0
- aruco-pose-0.2.0/examples/02_single_marker/simple_pose_estimation.py +86 -0
- aruco-pose-0.2.0/examples/03_multi_marker/README.md +250 -0
- aruco-pose-0.2.0/examples/03_multi_marker/multi_marker_fusion.py +9 -0
- aruco-pose-0.2.0/examples/04_custom_models/README.md +408 -0
- aruco-pose-0.2.0/examples/04_custom_models/dodecahedron_model.py +10 -0
- aruco-pose-0.2.0/examples/04_custom_models/dodecahedron_pose.py +605 -0
- aruco-pose-0.2.0/examples/04_custom_models/dodecahedron_tracking_demo.py +57 -0
- aruco-pose-0.2.0/examples/04_custom_models/generate_model.py +38 -0
- aruco-pose-0.2.0/examples/04_custom_models/generate_model_to_json.py +81 -0
- aruco-pose-0.2.0/examples/04_custom_models/gpt_aruco_pose_estimator.py +12 -0
- aruco-pose-0.2.0/examples/05_advanced/README.md +413 -0
- aruco-pose-0.2.0/examples/05_advanced/corner_tracking_demo.py +258 -0
- aruco-pose-0.2.0/examples/05_advanced/dense_refinement.py +9 -0
- aruco-pose-0.2.0/examples/05_advanced/gpt_pose_refiner.py +5 -0
- aruco-pose-0.2.0/examples/05_advanced/gpt_predictive_filter.py +5 -0
- aruco-pose-0.2.0/examples/05_advanced/optical_flow.py +15 -0
- aruco-pose-0.2.0/examples/README.md +332 -0
- aruco-pose-0.2.0/examples/pose_api_demo.py +177 -0
- aruco-pose-0.2.0/pyproject.toml +7 -0
- aruco-pose-0.2.0/requirements.txt +17 -0
- aruco-pose-0.2.0/setup.cfg +4 -0
- aruco-pose-0.2.0/setup.py +76 -0
- aruco-pose-0.2.0/tests/test_demo_controls.py +149 -0
- aruco-pose-0.2.0/tests/test_dodecahedron_model.py +63 -0
- aruco-pose-0.2.0/tests/test_dodecahedron_scaling.py +96 -0
- aruco-pose-0.2.0/tests/test_installation.py +327 -0
- aruco-pose-0.2.0/tests/test_package_name.py +66 -0
- aruco-pose-0.2.0/tests/test_pose_api.py +438 -0
- aruco-pose-0.2.0/tests/test_recovered_tracking.py +64 -0
- aruco-pose-0.2.0/tests/test_release_regressions.py +86 -0
- aruco-pose-0.2.0/tests/test_starter_workflow.py +244 -0
- aruco-pose-0.2.0/tests/test_visualization.py +64 -0
- aruco-pose-0.2.0/tools/README.md +495 -0
- aruco-pose-0.2.0/tools/__init__.py +1 -0
- aruco-pose-0.2.0/tools/cli.py +10 -0
- aruco-pose-0.2.0/tools/starter.py +4 -0
- aruco-pose-0.2.0/tools/visualize_aruco_extrinsics.py +271 -0
- aruco-pose-0.2.0/tools/visualize_dodecahedron_3d.py +42 -0
- aruco-pose-0.2.0/tools/visualize_dodecahedron_model.py +38 -0
- aruco-pose-0.2.0/tools/visualize_face_map.py +98 -0
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Contributing to ArUco Pose Estimation Toolkit
|
|
2
|
+
|
|
3
|
+
Thank you for considering contributing to this project!
|
|
4
|
+
|
|
5
|
+
## 🚀 Quick Start for Contributors
|
|
6
|
+
|
|
7
|
+
1. **Fork the repository** on GitHub
|
|
8
|
+
2. **Clone your fork** locally:
|
|
9
|
+
```bash
|
|
10
|
+
git clone https://github.com/YOUR_USERNAME/ArUco_Pose_Estimation.git
|
|
11
|
+
cd ArUco_Pose_Estimation
|
|
12
|
+
```
|
|
13
|
+
3. **Install in development mode**:
|
|
14
|
+
```bash
|
|
15
|
+
pip install -e .
|
|
16
|
+
```
|
|
17
|
+
4. **Create a branch** for your feature:
|
|
18
|
+
```bash
|
|
19
|
+
git checkout -b feature/my-new-feature
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## 📋 Development Guidelines
|
|
23
|
+
|
|
24
|
+
### Code Style
|
|
25
|
+
- Follow PEP 8 conventions
|
|
26
|
+
- Use type hints where appropriate
|
|
27
|
+
- Add docstrings to all public functions/classes
|
|
28
|
+
- Keep functions focused and modular
|
|
29
|
+
|
|
30
|
+
### Project Structure
|
|
31
|
+
- **Core functionality** → `aruco_pose/core/`
|
|
32
|
+
- **3D models** → `aruco_pose/models/`
|
|
33
|
+
- **Tracking algorithms** → `aruco_pose/tracking/`
|
|
34
|
+
- **Utilities** → `aruco_pose/utils/`
|
|
35
|
+
- **Examples** → `examples/` (organized by complexity)
|
|
36
|
+
- **CLI tools** → `tools/`
|
|
37
|
+
- **Tests** → `tests/`
|
|
38
|
+
|
|
39
|
+
### Adding New Features
|
|
40
|
+
|
|
41
|
+
1. **Create appropriate files** in the right directory
|
|
42
|
+
2. **Update `__init__.py`** files to export new classes/functions
|
|
43
|
+
3. **Add examples** showing usage
|
|
44
|
+
4. **Write tests** for new functionality
|
|
45
|
+
5. **Update documentation** in `docs/`
|
|
46
|
+
|
|
47
|
+
### Testing
|
|
48
|
+
|
|
49
|
+
Run tests before submitting:
|
|
50
|
+
```bash
|
|
51
|
+
pytest tests/
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Add new tests for your features in `tests/test_*.py`
|
|
55
|
+
|
|
56
|
+
## 📝 Documentation
|
|
57
|
+
|
|
58
|
+
- Update relevant README files when adding features
|
|
59
|
+
- Add docstrings to all public APIs
|
|
60
|
+
- Include usage examples in docstrings
|
|
61
|
+
- Update `docs/` files if architecture changes
|
|
62
|
+
|
|
63
|
+
## 🐛 Reporting Bugs
|
|
64
|
+
|
|
65
|
+
When reporting bugs, please include:
|
|
66
|
+
- Python version
|
|
67
|
+
- OpenCV version
|
|
68
|
+
- Operating system
|
|
69
|
+
- Minimal code to reproduce
|
|
70
|
+
- Expected vs actual behavior
|
|
71
|
+
- Error messages/stack traces
|
|
72
|
+
|
|
73
|
+
## 💡 Suggesting Features
|
|
74
|
+
|
|
75
|
+
Feature requests are welcome! Please:
|
|
76
|
+
- Check if it already exists in issues
|
|
77
|
+
- Explain the use case
|
|
78
|
+
- Provide example usage if possible
|
|
79
|
+
|
|
80
|
+
## 🔀 Pull Request Process
|
|
81
|
+
|
|
82
|
+
1. **Update documentation** for any changed functionality
|
|
83
|
+
2. **Add tests** for new features
|
|
84
|
+
3. **Ensure tests pass**: `pytest tests/`
|
|
85
|
+
4. **Update CHANGELOG** (if applicable)
|
|
86
|
+
5. **Submit PR** with clear description of changes
|
|
87
|
+
|
|
88
|
+
### PR Checklist
|
|
89
|
+
- [ ] Code follows project style
|
|
90
|
+
- [ ] All tests pass
|
|
91
|
+
- [ ] New tests added for new features
|
|
92
|
+
- [ ] Documentation updated
|
|
93
|
+
- [ ] Examples added/updated if needed
|
|
94
|
+
- [ ] No breaking changes (or clearly documented)
|
|
95
|
+
|
|
96
|
+
## 📦 Release Process
|
|
97
|
+
|
|
98
|
+
Maintainers will:
|
|
99
|
+
1. Review and merge PRs
|
|
100
|
+
2. Update version in `setup.py`
|
|
101
|
+
3. Update CHANGELOG
|
|
102
|
+
4. Create GitHub release
|
|
103
|
+
5. Tag version
|
|
104
|
+
|
|
105
|
+
## 🤝 Code of Conduct
|
|
106
|
+
|
|
107
|
+
- Be respectful and inclusive
|
|
108
|
+
- Welcome newcomers
|
|
109
|
+
- Focus on constructive feedback
|
|
110
|
+
- Help others learn
|
|
111
|
+
|
|
112
|
+
## 📧 Questions?
|
|
113
|
+
|
|
114
|
+
- Open an issue for technical questions
|
|
115
|
+
- Email maintainer for other inquiries: jshulgac@andrew.cmu.edu
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
Thank you for contributing! 🎉
|
aruco-pose-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
include LICENSE README.md CONTRIBUTING.md pyproject.toml setup.py requirements.txt
|
|
2
|
+
include docs/POSE_API.md docs/MODEL_SCALING.md docs/PACKAGE_MIGRATION.md docs/ROADMAP.md docs/PUBLISHING.md
|
|
3
|
+
recursive-include aruco_pose *.py
|
|
4
|
+
recursive-include tests *.py
|
|
5
|
+
recursive-include examples *.py *.md
|
|
6
|
+
recursive-include tools *.py *.md
|
|
7
|
+
recursive-include config *.json
|
|
8
|
+
recursive-include assets/starter *.json *.svg *.csv *.mp4
|
|
9
|
+
global-exclude __pycache__ *.py[cod] desktop.ini
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: aruco-pose
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: A robust toolkit for ArUco marker detection, pose estimation, and custom 3D model tracking
|
|
5
|
+
Home-page: https://github.com/Jshulgach/aruco-pose
|
|
6
|
+
Author: Jonathan Shulgach
|
|
7
|
+
Author-email: jshulgac@andrew.cmu.edu
|
|
8
|
+
License: Apache-2.0
|
|
9
|
+
Project-URL: Bug Reports, https://github.com/Jshulgach/aruco-pose/issues
|
|
10
|
+
Project-URL: Source, https://github.com/Jshulgach/aruco-pose
|
|
11
|
+
Keywords: aruco markers computer-vision pose-estimation opencv tracking
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Image Recognition
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
17
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Provides-Extra: docs
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
|
|
28
|
+
# aruco-pose
|
|
29
|
+
|
|
30
|
+
Print a rigid marker board, calibrate a camera, track its 6-DoF pose, and export CSV.
|
|
31
|
+
The supported starter workflow runs on a webcam **or the included synthetic videos**.
|
|
32
|
+
Python 3.9+; tested on Windows with Python 3.11 and OpenCV 4.14.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
From this repository's root, using a working Python installation:
|
|
37
|
+
|
|
38
|
+
```powershell
|
|
39
|
+
python -m venv .venv
|
|
40
|
+
# Windows PowerShell (activation is optional):
|
|
41
|
+
.venv\Scripts\python.exe -m pip install -e .
|
|
42
|
+
# Optional activation, so the remaining commands can use `python`:
|
|
43
|
+
.venv\Scripts\Activate.ps1
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
On macOS/Linux, use `.venv/bin/python` instead. In the commands below, `python`
|
|
47
|
+
means that environment's interpreter. You can activate it, or substitute its full
|
|
48
|
+
path. The installed `aruco-pose` command is equivalent to `python -m aruco_pose`.
|
|
49
|
+
`aruco-cli` remains a compatibility alias. The distribution is named `aruco-pose`
|
|
50
|
+
and the import package is `aruco_pose`; publishing instructions are in [the release guide](https://github.com/Jshulgach/aruco-pose/blob/main/docs/PUBLISHING.md).
|
|
51
|
+
Use a fresh environment: install only `opencv-contrib-python`, not both OpenCV
|
|
52
|
+
wheel variants, because they share the same `cv2` module. A graphical desktop is
|
|
53
|
+
needed only for `--preview` or printing SVGs through a browser.
|
|
54
|
+
|
|
55
|
+
## Try it without a camera
|
|
56
|
+
|
|
57
|
+
The repository includes a 30-view checkerboard clip and a six-second tracking clip
|
|
58
|
+
under `assets/starter/`. They are explicitly **synthetic perspective renders**,
|
|
59
|
+
not evidence of real-world accuracy. No downloads or camera calibration files from
|
|
60
|
+
your own machine are needed after installation.
|
|
61
|
+
|
|
62
|
+
```powershell
|
|
63
|
+
python -m aruco_pose kit calibrate --source assets/starter/calibration.mp4 --stride 1 --output output/sample_calibration.json
|
|
64
|
+
python -m aruco_pose kit track --source assets/starter/tracking.mp4 --model assets/starter/board.json --calibration output/sample_calibration.json --csv output/sample_poses.csv --output-video output/sample_tracked.mp4
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Expected: 120 CSV rows, 110 measured poses and 10 lost frames. Frames 50-59 hide the
|
|
68
|
+
whole board; frames 85-99 hide two markers while tracking continues with the other
|
|
69
|
+
two. Add `--preview` to see the overlay while processing, or open
|
|
70
|
+
`output/sample_tracked.mp4` afterward. Defaults are headless.
|
|
71
|
+
|
|
72
|
+
Outputs:
|
|
73
|
+
|
|
74
|
+
- `output/sample_calibration.json`: estimated camera matrix, distortion, resolution,
|
|
75
|
+
calibration RMS and view count.
|
|
76
|
+
- `output/sample_poses.csv`: one row per decoded frame, including explicit losses.
|
|
77
|
+
- `output/sample_poses.summary.json`: counts, model/calibration snapshots, units,
|
|
78
|
+
coordinate conventions, time basis and quality thresholds.
|
|
79
|
+
- `output/sample_tracked.mp4`: annotated video.
|
|
80
|
+
|
|
81
|
+
`assets/starter/reference_camera.json` and `ground_truth.csv` describe the known
|
|
82
|
+
synthetic camera and motion. The quick start deliberately estimates calibration
|
|
83
|
+
from the checkerboard clip instead of using the reference values. Regenerate all
|
|
84
|
+
sample inputs with `python -m aruco_pose kit sample --output output/new_sample`.
|
|
85
|
+
|
|
86
|
+
## Use a real camera: print -> calibrate -> track -> CSV
|
|
87
|
+
|
|
88
|
+
### 1. Print and mount the targets
|
|
89
|
+
|
|
90
|
+
```powershell
|
|
91
|
+
python -m aruco_pose kit print --output output/print
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Open the SVGs in a browser and print at **100% / actual size**, with fit-to-page,
|
|
95
|
+
headers and footers disabled. Targets are A4. Verify the 50 mm reference line and
|
|
96
|
+
measure the black marker squares: they must be 40 mm wide, with 20 mm gaps.
|
|
97
|
+
Mount the entire marker board flat on rigid backing; do not rearrange the markers.
|
|
98
|
+
The checkerboard is a separate target with **9 x 6 inner corners** and 20 mm squares.
|
|
99
|
+
Keep it flat too. Inspect the print for clipping or smudged black/white cells.
|
|
100
|
+
|
|
101
|
+
The generated `board.json` defines the exact four-marker layout, IDs 0-3 in
|
|
102
|
+
`DICT_5X5_100`. Keep it with its printed target. Never use a model with a different
|
|
103
|
+
printed scale or arrangement.
|
|
104
|
+
|
|
105
|
+
### 2. Calibrate at your tracking resolution
|
|
106
|
+
|
|
107
|
+
```powershell
|
|
108
|
+
python -m aruco_pose kit calibrate --source 0 --preview --output output/my_camera.json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Show the complete checkerboard and press **SPACE** to capture each view. Move and
|
|
112
|
+
tilt it between captures: near/far, left/right, top/bottom, with varied angles.
|
|
113
|
+
Use at least 8 distinct observations; aim for 20-30. Press **Q** to solve, or let
|
|
114
|
+
capture stop at 40 accepted views. Keep camera resolution, focus and zoom fixed
|
|
115
|
+
between calibration and tracking. The command reports RMS reprojection error;
|
|
116
|
+
values above 1 pixel prompt a warning. Low RMS alone does not establish accuracy.
|
|
117
|
+
|
|
118
|
+
For a checkerboard video instead, pass its path and choose `--stride 10` (or a
|
|
119
|
+
suitable interval). Change `--cols`, `--rows` and `--square-size` only when using a
|
|
120
|
+
different measured calibration target. Camera indexes such as `0` and `1` are
|
|
121
|
+
supported. If you need a particular capture resolution, configure the camera
|
|
122
|
+
beforehand and confirm it remains unchanged for both steps.
|
|
123
|
+
|
|
124
|
+
### 3. Track and export
|
|
125
|
+
|
|
126
|
+
```powershell
|
|
127
|
+
python -m aruco_pose kit track --source 0 --model output/print/board.json --calibration output/my_camera.json --csv output/my_poses.csv --preview --output-video output/my_tracking.mp4
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Press **Q** to stop. For a recorded board video, replace `0` with its path. At least
|
|
131
|
+
two recognized board markers are required by default. `--min-markers 1` permits
|
|
132
|
+
single-marker estimates but increases planar-pose ambiguity. Unknown IDs are
|
|
133
|
+
ignored. The shared solver rejects corner/marker outliers before fitting. A pose is
|
|
134
|
+
rejected without majority support, when inlier reprojection RMSE exceeds
|
|
135
|
+
`--max-error` (default 3 pixels), or when accepted points have invalid depth.
|
|
136
|
+
Close planar alternatives are reported as ambiguous unless a recent compatible
|
|
137
|
+
measurement resolves the choice. No prediction is substituted
|
|
138
|
+
for a missing measurement. The entire CSV remains available after a normal quit.
|
|
139
|
+
|
|
140
|
+
## Understand the CSV
|
|
141
|
+
|
|
142
|
+
| Columns | Meaning |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `frame`, `time_s` | Zero-based frame and elapsed seconds; video time is frame/FPS, camera time is monotonic host receipt time. |
|
|
145
|
+
| `object_id`, `status` | `starter_board`; `measured`, `lost`, `rejected`, or `ambiguous`. |
|
|
146
|
+
| `marker_ids`, `marker_count` | Accepted inlier marker IDs separated by semicolons, and their count. |
|
|
147
|
+
| `tx_m`, `ty_m`, `tz_m` | Board origin in camera coordinates, in meters. |
|
|
148
|
+
| `qx`, `qy`, `qz`, `qw` | Unit quaternion rotating board coordinates into camera coordinates. |
|
|
149
|
+
| `reprojection_rmse_px` | Root mean squared 2D corner-distance residual; not a physical accuracy estimate. |
|
|
150
|
+
|
|
151
|
+
Transform: `p_camera = R_object_to_camera @ p_object + t_object_to_camera`.
|
|
152
|
+
Camera axes: **x right, y down, z forward**. Board origin: center of the four-marker
|
|
153
|
+
layout, x printed right, y printed down, z into the paper. This is not a robot's
|
|
154
|
+
world-frame pose. Lost/rejected/ambiguous rows have blank position/quaternion fields. Do not
|
|
155
|
+
replace blanks with zeros or carry forward old poses without labeling them.
|
|
156
|
+
|
|
157
|
+
File timestamps assume constant frame rate. Camera timestamps describe host frame
|
|
158
|
+
receipt, not hardware exposure time. The calibration resolution is checked against
|
|
159
|
+
every frame; mismatches fail rather than silently scaling camera intrinsics.
|
|
160
|
+
|
|
161
|
+
## Troubleshooting
|
|
162
|
+
|
|
163
|
+
- **No detections:** verify print scale/dictionary, lighting, focus, full black
|
|
164
|
+
borders and white margins; move closer until the markers occupy more pixels.
|
|
165
|
+
- **Not enough calibration views:** show the complete checkerboard, use inner-corner
|
|
166
|
+
counts, and vary its position/tilt. Reduce video stride for short clips.
|
|
167
|
+
- **Wrong physical distance:** measure the print and verify the matching model.
|
|
168
|
+
Calibration square size and marker positions must be in meters.
|
|
169
|
+
- **Pose flips/jitter:** planar boards have ambiguous poses in difficult views;
|
|
170
|
+
improve viewing angle, resolution and lighting. The shared solver rejects corner/marker outliers and flags close planar
|
|
171
|
+
alternatives; a recent compatible measurement may resolve them. It does not
|
|
172
|
+
smooth poses or substitute predictions for missing observations.
|
|
173
|
+
- **Video cannot open/write:** confirm the path and codec. Output `.avi` uses MJPG;
|
|
174
|
+
other output extensions use mp4v (use `.mp4`).
|
|
175
|
+
- **Python command fails:** choose an installed interpreter explicitly; do not reuse
|
|
176
|
+
an old virtual environment pointing at a removed Python installation.
|
|
177
|
+
|
|
178
|
+
## Shared Python pose API
|
|
179
|
+
|
|
180
|
+
The CLI and updated tracking examples now share `Tracker` and `PoseResult`:
|
|
181
|
+
|
|
182
|
+
```python
|
|
183
|
+
from aruco_pose import Tracker, TrackerConfig
|
|
184
|
+
# model is an explicit-corner model dict; K/D are camera intrinsics/distortion.
|
|
185
|
+
tracker = Tracker(model, K, D, config=TrackerConfig(min_markers=2))
|
|
186
|
+
result = tracker.process(frame, timestamp_s=timestamp_s, previous=previous_result)
|
|
187
|
+
if result.pose is not None:
|
|
188
|
+
position_m = result.pose.translation_m
|
|
189
|
+
quaternion_xyzw = result.pose.quaternion_xyzw
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
See [the complete API guide](https://github.com/Jshulgach/aruco-pose/blob/main/docs/POSE_API.md) for a runnable example, transform
|
|
193
|
+
conventions, outlier/ambiguity policies and legacy adapters. Run
|
|
194
|
+
`python examples/pose_api_demo.py --preview` for a looping camera-free Python
|
|
195
|
+
example. It writes no data files unless `--csv PATH` is passed. Stop with Q, Escape,
|
|
196
|
+
window close or Ctrl+C; use `--seconds 20` for a time limit, or `--once` for one pass. The CSV/summary
|
|
197
|
+
schema is version 2: old columns are preserved, with support, reason, candidate and
|
|
198
|
+
frame diagnostics appended. Read fields by name and handle `ambiguous` rows.
|
|
199
|
+
|
|
200
|
+
See [package migration notes](https://github.com/Jshulgach/aruco-pose/blob/main/docs/PACKAGE_MIGRATION.md) when updating an existing
|
|
201
|
+
installation or imports from the old `src` namespace.
|
|
202
|
+
|
|
203
|
+
## Development and other examples
|
|
204
|
+
|
|
205
|
+
```powershell
|
|
206
|
+
python -m pip install -e ".[dev]"
|
|
207
|
+
python -m pytest -q
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
The starter `kit` commands are the supported end-to-end path. Older top-level CLI
|
|
211
|
+
commands and examples are experimental and have different formats. Dodecahedron
|
|
212
|
+
tracking remains available under `examples/04_custom_models/`; see
|
|
213
|
+
[model scaling](https://github.com/Jshulgach/aruco-pose/blob/main/docs/MODEL_SCALING.md) before using the saved 17 mm and 25 mm models.
|
|
214
|
+
The flat starter board uses a separate explicit-corner model, not those legacy JSON
|
|
215
|
+
formats. [Roadmap](https://github.com/Jshulgach/aruco-pose/blob/main/docs/ROADMAP.md) describes the steps toward one shared API and ROS 2.
|
|
216
|
+
|
|
217
|
+
Sample assets are generated by this repository and covered by its Apache 2.0 license.
|
|
218
|
+
|
|
219
|
+
## Acknowledgements
|
|
220
|
+
|
|
221
|
+
Built on OpenCV ArUco and inspired by the original
|
|
222
|
+
[GSNCodes ArUco examples](https://github.com/GSNCodes/ArUCo-Markers-Pose-Estimation-Generation-Python).
|
|
223
|
+
See [LICENSE](https://github.com/Jshulgach/aruco-pose/blob/main/LICENSE) for the existing Apache 2.0 terms.
|
|
224
|
+
|
|
225
|
+
The [release audit](https://github.com/Jshulgach/aruco-pose/blob/main/docs/RELEASE_AUDIT.md) records verified checks and remaining
|
|
226
|
+
release decisions, including the public package namespace and older media.
|