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.

Returns:

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.

Returns:

The projector resolution.

zivid.projection.projector_resolution(camera) — see Projector.

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.

Parameters:

  • camera – Reference to camera instance

  • image – Image to display, provided in BGRA format

Returns:

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.

Parameters:

  • camera – Reference to camera instance

  • image – Image to display, provided in BGRA format

Returns:

A handle to the projected image

zivid.projection.show_image_bgra(camera, image) — see Projector.

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.

Parameters:

settings – Settings to use for the capture

Returns:

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.

Parameters:

settings – Settings2D to use for the capture

Returns:

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.

Parameters:

settings – Settings2D to use for the capture

Returns:

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.

Returns:

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.

Parameters:

settings – Settings to use for the capture

Returns:

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.

Parameters:

settings2D – Settings2D to use for the capture

Returns:

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.

Parameters:

settings2D – Settings2D to use for the capture

Returns:

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.

zivid.projection.ProjectedImage — see Projector.

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.

Parameters:

  • camera – Reference to camera instance.

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

Returns:

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.

Parameters:

  • camera – Reference to camera instance.

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

Returns:

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.

Parameters:

  • camera – Reference to camera instance.

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

Returns:

List of 2D projector pixel coordinates

zivid.projection.pixels_from_3d_points(camera, points) — see Projector.

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).

Parameters:

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).

Parameters:

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

zivid.calibration.detect_feature_points(point_cloud) — see Projector.

See also