Add copy utilities for apriltag_detection_t and apriltag_detector_t

- Add apriltag_detection_copy() and apriltag_detections_copy() to deep copy
  detection results including the matd_t* H homography matrix.
- Add apriltag_detector_copy() to clone detector configuration by copying
  all scalar fields and reinitializing pointer fields (tag_families, tp, wp)
  to independent default values to avoid shared ownership and double-free
  issues on destruction.

Author: fspindle

README.md

@@ -193,6 +193,14 @@ Note: The tag size should not be measured from the outside of the tag. The tag s
 ### Coordinate System
 The coordinate system has the origin at the camera center. The z-axis points from the camera center out the camera lens. The x-axis is to the right in the image taken by the camera, and y is down. The tag's coordinate frame is centered at the center of the tag. From the viewer's perspective, the x-axis is to the right, y-axis down, and z-axis is into the tag.
 
+Utility Functions
+=================
+AprilTag 3 now includes helper functions for deep-copying structures, which is essential for multi-threaded applications or when you need to store detections beyond the detector's lifecycle.
+
+* `apriltag_detector_copy(td)`: Creates a clone of the detector configuration.
+* `apriltag_detections_copy(detections)`: Returns a new `zarray_t` with deep copies of all `apriltag_detection_t` objects.
+* `apriltag_detection_copy(src, dst)`: Performs a deep copy of a single detection into an existing structure.
+
 Debugging
 =========
 

apriltag.c

@@ -1496,3 +1496,58 @@ image_u8_t *apriltag_to_image(apriltag_family_t *fam, uint32_t idx)
     }
     return im;
 }
+
+void apriltag_detection_copy(apriltag_detection_t* src, apriltag_detection_t* dst)
+{
+    assert(src != NULL);
+    assert(dst != NULL);
+
+    if (dst->H) {
+        matd_destroy(dst->H);
+    }
+    dst->H = matd_copy(src->H);
+
+    dst->c[0] = src->c[0];
+    dst->c[1] = src->c[1];
+
+    for (int i = 0; i < 4; i++) {
+        for (int j = 0; j < 2; j++) {
+            dst->p[i][j] = src->p[i][j];
+        }
+    }
+
+    dst->id = src->id;
+    dst->family = src->family;
+    dst->hamming = src->hamming;
+    dst->decision_margin = src->decision_margin;
+}
+
+zarray_t* apriltag_detections_copy(zarray_t* detections)
+{
+    zarray_t* detections_copy = zarray_create(sizeof(apriltag_detection_t*));
+    for (int i = 0; i < zarray_size(detections); i++) {
+        apriltag_detection_t* det;
+        zarray_get(detections, i, &det);
+
+        apriltag_detection_t* det_copy = (apriltag_detection_t*)calloc(1, sizeof(apriltag_detection_t));
+        apriltag_detection_copy(det, det_copy);
+        zarray_add(detections_copy, &det_copy);
+    }
+
+    return detections_copy;
+}
+
+apriltag_detector_t *apriltag_detector_copy(apriltag_detector_t *src)
+{
+    apriltag_detector_t *dst = (apriltag_detector_t *)malloc(sizeof(apriltag_detector_t));
+    // Shallow copy of all scalar fields
+    *dst = *src;
+
+    // Reinitialize pointer fields to independent default values to avoid shared ownership and double-free issues
+    dst->tag_families = zarray_create(sizeof(apriltag_family_t *));
+    dst->tp = timeprofile_create();
+    dst->wp = workerpool_create(src->nthreads);
+
+    return dst;
+}
+

apriltag.h

@@ -267,6 +267,15 @@ void apriltag_detection_destroy(apriltag_detection_t *det);
 // destroys the array AND the detections within it.
 void apriltag_detections_destroy(zarray_t *detections);
 
+// Performs a deep copy of an AprilTag detection structure from a source to a destination.
+void apriltag_detection_copy(apriltag_detection_t* src, apriltag_detection_t* dst);
+
+// Creates a complete deep copy of a list of AprilTag detections.
+zarray_t* apriltag_detections_copy(zarray_t* detections);
+
+// Clones an AprilTag detector configuration into a new instance.
+apriltag_detector_t *apriltag_detector_copy(apriltag_detector_t *src);
+
 // Renders the apriltag.
 // Caller is responsible for calling image_u8_destroy on the image
 image_u8_t *apriltag_to_image(apriltag_family_t *fam, uint32_t idx);