|
| 1 | +"""Module for experimental projection features. This API may change in the future.""" |
| 2 | + |
| 3 | +import _zivid |
| 4 | +from zivid.frame_2d import Frame2D |
| 5 | +from zivid.settings_2d import Settings2D, _to_internal_settings2d |
| 6 | + |
| 7 | + |
| 8 | +class ProjectedImage: |
| 9 | + """A handle to a 2D image being displayed on a Zivid camera's projector. |
| 10 | +
|
| 11 | + The image projection will stop either when the instance is destroyed, when the stop() method is called, |
| 12 | + or when exiting the "with" block if used as a context manager. |
| 13 | + """ |
| 14 | + |
| 15 | + def __init__(self, impl): |
| 16 | + """Initialize ProjectedImage wrapper. |
| 17 | +
|
| 18 | + This constructor is only used internally, and should not be called by the end-user. |
| 19 | +
|
| 20 | + Args: |
| 21 | + impl: Reference to internal/back-end instance. |
| 22 | +
|
| 23 | + Raises: |
| 24 | + TypeError: If argument does not match the expected internal class. |
| 25 | + """ |
| 26 | + if isinstance(impl, _zivid.ProjectedImage): |
| 27 | + self.__impl = impl |
| 28 | + else: |
| 29 | + raise TypeError( |
| 30 | + "Unsupported type for argument impl. Got {}, expected {}.".format( |
| 31 | + type(impl), type(_zivid.ProjectedImage) |
| 32 | + ) |
| 33 | + ) |
| 34 | + |
| 35 | + def __str__(self): |
| 36 | + return str(self.__impl) |
| 37 | + |
| 38 | + def capture(self, settings2d): |
| 39 | + """Capture a single 2D frame without stopping the ongoing image projection. |
| 40 | +
|
| 41 | + This method returns right after the acquisition of the image is complete. This function can only be used |
| 42 | + with a zero-brightness 2D capture, otherwise it will interfere with the projected image. An exception |
| 43 | + will be thrown if settings contains brightness > 0. |
| 44 | +
|
| 45 | + Args: |
| 46 | + settings2d: A Settings2D instance to be used for 2D capture. |
| 47 | +
|
| 48 | + Returns: |
| 49 | + A Frame2D containing a 2D image plus metadata. |
| 50 | +
|
| 51 | + Raises: |
| 52 | + TypeError: If argument is not a Settings2D. |
| 53 | + """ |
| 54 | + |
| 55 | + if isinstance(settings2d, Settings2D): |
| 56 | + return Frame2D(self.__impl.capture(_to_internal_settings2d(settings2d))) |
| 57 | + raise TypeError("Unsupported settings type: {}".format(type(settings2d))) |
| 58 | + |
| 59 | + def stop(self): |
| 60 | + """Stop the ongoing image projection.""" |
| 61 | + self.__impl.stop() |
| 62 | + |
| 63 | + def active(self): |
| 64 | + """Check if a handle is associated with an ongoing image projection. |
| 65 | +
|
| 66 | + Returns: |
| 67 | + A boolean indicating projection state. |
| 68 | + """ |
| 69 | + return self.__impl.active() |
| 70 | + |
| 71 | + def release(self): |
| 72 | + """Release the underlying resources and stop projection.""" |
| 73 | + try: |
| 74 | + impl = self.__impl |
| 75 | + except AttributeError: |
| 76 | + pass |
| 77 | + else: |
| 78 | + impl.release() |
| 79 | + |
| 80 | + def __enter__(self): |
| 81 | + return self |
| 82 | + |
| 83 | + def __exit__(self, exception_type, exception_value, traceback): |
| 84 | + self.release() |
| 85 | + |
| 86 | + def __del__(self): |
| 87 | + self.release() |
| 88 | + |
| 89 | + |
| 90 | +def projector_resolution(camera): |
| 91 | + """Get the resolution of the internal projector in the Zivid camera. |
| 92 | +
|
| 93 | + Args: |
| 94 | + camera: The Camera instance to get the projector resolution of. |
| 95 | +
|
| 96 | + Returns: |
| 97 | + The resolution as a tuple (height,width). |
| 98 | + """ |
| 99 | + return _zivid.projection.projector_resolution( |
| 100 | + camera._Camera__impl # pylint: disable=protected-access |
| 101 | + ) |
| 102 | + |
| 103 | + |
| 104 | +def show_image_bgra(camera, image_bgra): |
| 105 | + """Display a 2D color image using the projector. |
| 106 | +
|
| 107 | + The image resolution needs to be the same as the resolution obtained from the projector_resolution |
| 108 | + function for the camera. This function returns a ProjectedImage instance. Projection will continue |
| 109 | + until this object is destroyed, if its stop() method is called, or if another capture is initialized |
| 110 | + on the same camera. The ProjectedImage object can be used as a context manager, in which case the |
| 111 | + projection will stop when exiting the "with" block. |
| 112 | +
|
| 113 | + Args: |
| 114 | + camera: The Camera instance to project with. |
| 115 | + image_bgra: The image to project in the form of a HxWx4 numpy array with BGRA colors. |
| 116 | +
|
| 117 | + Returns: |
| 118 | + A handle in the form of a ProjectedImage instance. |
| 119 | + """ |
| 120 | + |
| 121 | + return ProjectedImage( |
| 122 | + _zivid.projection.show_image_bgra( |
| 123 | + camera._Camera__impl, # pylint: disable=protected-access |
| 124 | + image_bgra, |
| 125 | + ) |
| 126 | + ) |
| 127 | + |
| 128 | + |
| 129 | +def pixels_from_3d_points(camera, points): |
| 130 | + """Get 2D projector pixel coordinates corresponding to 3D points relative to the camera. |
| 131 | +
|
| 132 | + This function takes 3D points in the camera's reference frame and converts them to the projector frame |
| 133 | + using the internal calibration of a Zivid camera. In a Zivid point cloud, each point corresponds to a |
| 134 | + pixel coordinate in the camera, but the projector has a slight offset. The translation of each point |
| 135 | + depends on the distance between the camera and the point, as well as the distance and angle between the |
| 136 | + camera and the projector. |
| 137 | +
|
| 138 | + Args: |
| 139 | + camera: The Camera instance that the 3D points are in the frame of. |
| 140 | + points: A list of 3D (XYZ) points as List[List[float[3]]] or Nx3 Numpy array. |
| 141 | +
|
| 142 | + Returns: |
| 143 | + The corresponding 2D (XY) points in the projector (List[List[float[2]]]) |
| 144 | + """ |
| 145 | + |
| 146 | + return _zivid.projection.pixels_from_3d_points( |
| 147 | + camera._Camera__impl, # pylint: disable=protected-access |
| 148 | + points, |
| 149 | + ) |
0 commit comments