Projection

APIs for displaying images on the Zivid camera's built-in projector and for mapping 3D points to projector pixels. See Projector for the full tutorial.

        %%{init: {'themeVariables': {'fontSize': '18px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 35}}}%%
flowchart LR
  Camera
  ImageBGRA["Image<ColorBGRA>"]
  PointXYZ["[PointXYZ]"]
  Settings2D

  subgraph projectionNs [Projection]
    projectorResolutionOp(["projectorResolution()"])
    showImageOp(["showImage()"])
    pixelsFrom3DPointsOp(["pixelsFrom3DPoints()"])
    Resolution
    ProjectedImage
    capture2DOp(["capture2D()"])
    stopOp(["stop()"])
    activeOp(["active()"])
  end

  Frame2D
  PointXY["[PointXY]"]

  Camera -.-> projectorResolutionOp --> Resolution
  Camera -.-> showImageOp --> ProjectedImage
  ImageBGRA -.-> showImageOp
  Camera -.-> pixelsFrom3DPointsOp --> PointXY
  PointXYZ -.-> pixelsFrom3DPointsOp
  Settings2D -.-> capture2DOp
  ProjectedImage --> capture2DOp --> Frame2D
  ProjectedImage --> stopOp
  ProjectedImage --> activeOp

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class Camera,ImageBGRA,PointXYZ,Settings2D,ProjectedImage,Resolution,Frame2D,PointXY zividClass
  class projectorResolutionOp,showImageOp,pixelsFrom3DPointsOp,capture2DOp,stopOp,activeOp api

projectorResolution

Returns the pixel resolution of the projector in the connected camera. Required to create a correctly-sized image before calling showImage.

Resolution Zivid::Projection::projectorResolution(const Camera &camera)

Returns the resolution of the internal projector in the Zivid camera.

戻り値:

The projector resolution

Zivid::NET::Projection::Projection::ProjectorResolution(Camera)

class Projection

Public Static Functions

static Resolution ^ ProjectorResolution (Camera ^ camera)

Get the resolution of the internal projector in the Zivid camera.

戻り値:

The projector resolution.

projector_resolution(camera: Camera) → tuple

Get the resolution of the internal projector in the Zivid camera.

パラメータ:

camera -- The Camera instance to get the projector resolution of.

戻り値:

The resolution as a tuple (height,width).

showImage

Starts projecting an image and returns a handle. Projection continues as long as the handle is alive. Stops automatically when the handle is destroyed, when pixelsFrom3DPoints is called, or when a 3D capture starts.

ProjectedImage Zivid::Projection::showImage(Camera &camera, const Image<ColorBGRA> &image)

Display a 2D color image using the projector.

The image resolution needs to be the same as the resolution obtained from the projectorResolution(const Camera &camera) function for the camera. To project the image, the returned projected image handle must be kept alive. The projection will stop when the handle goes out of scope, if the stop() function is called on the handle, or if another capture is initiated on the camera.

パラメータ:

  • camera -- Reference to camera instance

  • image -- Image to display, provided in BGRA format

戻り値:

A handle to the projected image

Zivid::NET::Projection::Projection::ShowImage(Camera, ImageBGRA)

class Projection

Public Static Functions

static ProjectedImage ^ ShowImage (Camera ^ camera, ImageBGRA ^ image)

Display a 2D color image using the projector.

The image resolution needs to be the same as the resolution obtained from the ProjectorResolution function. To project the image, the returned projected image handle must be kept alive. The projection will stop when the handle goes out of scope, if the Stop() function is called on the handle, or if another capture is initiated on the camera.

パラメータ:

  • camera -- Reference to camera instance

  • image -- Image to display, provided in BGRA format

戻り値:

A handle to the projected image

show_image_bgra(
camera: Camera,
image_bgra: ndarray,
) → ProjectedImage

Display a 2D color image using the projector.

The image resolution needs to be the same as the resolution obtained from the projector_resolution function for the camera. This function returns a ProjectedImage instance. Projection will continue until this object is destroyed, if its stop() method is called, or if another capture is initialized on the same camera. The ProjectedImage object can be used as a context manager, in which case the projection will stop when exiting the "with" block.

パラメータ:

  • camera -- The Camera instance to project with.

  • image_bgra -- The image to project in the form of a HxWx4 numpy array with BGRA colors.

戻り値:

A handle in the form of a ProjectedImage instance.

ProjectedImage

Handle to an ongoing projection. Provides capture2D, stop, and active.

class ProjectedImage

A handle to a 2D image being displayed on Zivid camera's projector.

The image projection will stop when this handle goes out of scope, if another operation is started on the camera or if the stop() method on this handle is called.

Public Functions

Frame2D capture2D(const Settings &settings)

Capture a single 2D frame without stopping the ongoing image projection.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

This overload is provided for convenience. Note that only the Settings2D part under Settings::Color will be used for the capture. The other parts of the settings will be ignored.

パラメータ:

settings -- Settings to use for the capture

戻り値:

A frame containing a 2D image and metadata

Frame2D capture2D(const Settings2D &settings)

Capture a single 2D frame without stopping the ongoing image projection.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

パラメータ:

settings -- Settings2D to use for the capture

戻り値:

A frame containing a 2D image and metadata

Frame2D capture(const Settings2D &settings)

Capture a single 2D frame without stopping the ongoing image projection.

This method is deprecated and will be removed in the next SDK major release (3.0). It is replaced by capture2D.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

パラメータ:

settings -- Settings2D to use for the capture

戻り値:

A frame containing a 2D image and metadata

void stop()

Stops the ongoing image projection.

bool active() const

Check if a handle is associated with an ongoing image projection.

戻り値:

A bool indicating the active status.

std::string toString() const

Get string representation of the projected image.

class ProjectedImage

Handle to a projected image.

The projector will continue to project the same image until its handle is disposed, its Stop method is called, or a capture is performed.

Public Functions

Frame2D ^ Capture2D (Settings ^ settings)

Capture a single 2D frame without stopping the ongoing image projection.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

This overload is provided for convenience. Note that only the Settings2D part under Settings::Color will be used for the capture. The other parts of the settings will be ignored.

パラメータ:

settings -- Settings to use for the capture

戻り値:

A frame containing a 2D image and metadata

Frame2D ^ Capture2D (Settings2D ^ settings2D)

Capture a single 2D frame without stopping the ongoing image projection.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

パラメータ:

settings2D -- Settings2D to use for the capture

戻り値:

A frame containing a 2D image and metadata

Frame2D ^ Capture (Settings2D ^ settings2D)

Capture a single 2D frame without stopping the ongoing image projection.

This method is deprecated and will be removed in the next SDK major release (3.0). It is replaced by Capture2D(Settings2D ^settings2D).

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

パラメータ:

settings2D -- Settings2D to use for the capture

戻り値:

A frame containing a 2D image and metadata

void Stop()

Stop the ongoing image projection.

System::String ^ ToString () override

Get a string representation of the projected image.

Properties

System::Boolean Active

Check if a handle is associated with an ongoing image projection.

Return:

True if the image is still being projected, false otherwise.

class ProjectedImage(impl)

A handle to a 2D image being displayed on a Zivid camera's projector.

The image projection will stop either when the instance is destroyed, when the stop() method is called, or when exiting the "with" block if used as a context manager.

active() → bool

Check if a handle is associated with an ongoing image projection.

戻り値:

A boolean indicating projection state.

capture(
settings2d: Settings2D,
) → Frame2D

Capture a single 2D frame without stopping the ongoing image projection.

This method is deprecated as of SDK 2.15 and will be removed in the next SDK major version (3.0). Use capture_2d instead.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

パラメータ:

settings2d -- A Settings2D instance to be used for 2D capture.

戻り値:

A Frame2D containing a 2D image plus metadata.

例外:

TypeError -- If argument is not a Settings2D.

capture_2d(
settings: Settings | Settings2D,
) → Frame2D

Capture a single 2D frame without stopping the ongoing image projection.

This method returns right after the acquisition of the image is complete.

To match the projector frequency of 120 Hz, the exposure time should be set to 8333 microseconds, otherwise the projected image brightness in the captured image may appear inconsistent over repeated captures.

Some settings cannot be used to capture while projecting, depending on the camera model:

  • Not all camera models support capturing rgb colors while projecting. An exception will be thrown if Settings2D/Sampling/Color is set to rgb and the camera does not support capturing rgb colors while projecting. Those cameras must use grayscale instead.

  • When Settings2D/Sampling/Color is set to rgb the brightness must be 0 in all acquisitions, otherwise an exception will be thrown.

  • When Settings2D/Sampling/Color is set to grayscale the brightness may be set to some value > 0. This value will override the brightness of the projection to control the contrast between the scene and the projected image. This will cause the projected image to flicker while the camera is capturing. If the brightness is set to 0 the image projection will be uninterrupted.

パラメータ:

settings -- Settings to use for the capture. Can be either a Settings2D instance or a Settings instance. If a Settings instance is provided, only the Settings.color part is used. An exception is thrown if the Settings.color part is not set.

戻り値:

A Frame2D containing a 2D image plus metadata.

例外:

TypeError -- If argument is not either a Settings2D or a Settings instance.

release() → None

Release the underlying resources and stop projection.

stop() → None

Stop the ongoing image projection.

pixelsFrom3DPoints

Converts 3D points (in the camera frame) to 2D projector pixel coordinates using the camera's internal calibration. Used to project content onto known 3D locations in the scene.

std::vector<PointXY> Zivid::Projection::pixelsFrom3DPoints(const Camera &camera, const std::vector<PointXYZ> &points)

Get 2D projector pixel coordinates corresponding to 3D points relative to the camera.

This function takes 3D points in the camera's reference frame and converts them to the projector frame using the internal calibration of a Zivid camera. In a Zivid point cloud, each point corresponds to a pixel coordinate in the camera, but the projector has a slight offset. The translation of each point depends on the distance between the camera and the point, as well as the distance and angle between the camera and the projector.

パラメータ:

  • camera -- Reference to camera instance.

  • points -- List of 3D points in the camera frame

戻り値:

List of 2D projector pixel coordinates

Array2D<PointXY> Zivid::Projection::pixelsFrom3DPoints(const Camera &camera, const Array2D<PointXYZ> &points)

Get 2D projector pixel coordinates corresponding to 3D points relative to the camera.

This function takes 3D points in the camera's reference frame and converts them to the projector frame using the internal calibration of a Zivid camera. In a Zivid point cloud, each point corresponds to a pixel coordinate in the camera, but the projector has a slight offset. The translation of each point depends on the distance between the camera and the point, as well as the distance and angle between the camera and the projector.

パラメータ:

  • camera -- Reference to camera instance.

  • points -- Two-dimensional array of 3D points in the camera frame

戻り値:

Two-dimensional array of 2D projector pixel coordinates

Zivid::NET::Projection::Projection::PixelsFrom3DPoints(Camera, IList<PointXYZ>)

class Projection

Public Static Functions

static System::Collections::Generic::IList< PointXY > ^ PixelsFrom3DPoints (Camera ^ camera, System::Collections::Generic::IList< PointXYZ > ^ points)

Get 2D projector pixel coordinates corresponding to 3D points relative to the camera.

This function takes 3D points in the camera's reference frame and converts them to the projector frame using the internal calibration of a Zivid camera. In a Zivid point cloud, each point corresponds to a pixel coordinate in the camera, but the projector has a slight offset. The translation of each point depends on the distance between the camera and the point, as well as the distance and angle between the camera and the projector.

パラメータ:

  • camera -- Reference to camera instance.

  • points -- List of 3D points in the camera frame

戻り値:

List of 2D projector pixel coordinates

pixels_from_3d_points(
camera: Camera,
points: list | ndarray,
) → list

Get 2D projector pixel coordinates corresponding to 3D points relative to the camera.

This function takes 3D points in the camera's reference frame and converts them to the projector frame using the internal calibration of a Zivid camera. In a Zivid point cloud, each point corresponds to a pixel coordinate in the camera, but the projector has a slight offset. The translation of each point depends on the distance between the camera and the point, as well as the distance and angle between the camera and the projector.

パラメータ:

  • camera -- The Camera instance that the 3D points are in the frame of.

  • points -- A list of 3D (XYZ) points as List[List[float[3]]] or Nx3 Numpy array.

戻り値:

The corresponding 2D (XY) points in the projector (List[List[float[2]]])

detectFeaturePoints

Detects checkerboard feature points in a point cloud. Used to build a projector image that overlays content onto known 3D positions (see Projector).

DetectionResult Zivid::Calibration::detectFeaturePoints(const PointCloud &cloud)

Detects feature points from a calibration board in a point cloud.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

This method is deprecated as of SDK 2.9. Instead you should use Zivid::Calibration::detectCalibrationBoard(const Zivid::Frame &frame) or Zivid::Calibration::detectCalibrationBoard(Zivid::Camera &camera).

パラメータ:

cloud -- Point cloud from a frame containing an image of a calibration board

class Detector

Public Static Functions

static DetectionResult ^ DetectFeaturePoints (PointCloud ^ pointCloud)

Detects feature points from a calibration board in a point cloud.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

This method is deprecated as of SDK 2.9. Instead you should use Calibration::Detector::DetectCalibrationBoard(Frame ^frame).

パラメータ:

pointCloud -- Point cloud from a frame containing an image of a calibration board

detect_feature_points(
point_cloud: PointCloud,
) → DetectionResult

Detect feature points from a calibration object in a point cloud.

パラメータ:

point_cloud -- PointCloud containing a calibration object

戻り値:

A DetectionResult instance

See also