001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package edu.wpi.first.cscore;
006
007import org.opencv.core.Mat;
008
009/**
010 * A sink for user code to accept video frames as OpenCV images. These sinks require the WPILib
011 * OpenCV builds. For an alternate OpenCV, see the documentation how to build your own with RawSink.
012 */
013public class CvSink extends ImageSink {
014  /**
015   * Create a sink for accepting OpenCV images. WaitForFrame() must be called on the created sink to
016   * get each new image.
017   *
018   * @param name Source name (arbitrary unique identifier)
019   */
020  public CvSink(String name) {
021    super(CameraServerCvJNI.createCvSink(name));
022  }
023
024  /// Create a sink for accepting OpenCV images in a separate thread.
025  /// A thread will be created that calls WaitForFrame() and calls the
026  /// processFrame() callback each time a new frame arrives.
027  /// @param name Source name (arbitrary unique identifier)
028  /// @param processFrame Frame processing function; will be called with a
029  ///        time=0 if an error occurred.  processFrame should call GetImage()
030  ///        or GetError() as needed, but should not call (except in very
031  ///        unusual circumstances) WaitForImage().
032  // public CvSink(wpi::StringRef name,
033  //       std::function<void(uint64_t time)> processFrame) {
034  //  super(CameraServerJNI.createCvSinkCallback(name, processFrame));
035  // }
036
037  /**
038   * Wait for the next frame and get the image. Times out (returning 0) after 0.225 seconds. The
039   * provided image will have three 3-bit channels stored in BGR order.
040   *
041   * @param image Where to store the image.
042   * @return Frame time, or 0 on error (call GetError() to obtain the error message)
043   */
044  public long grabFrame(Mat image) {
045    return grabFrame(image, 0.225);
046  }
047
048  /**
049   * Wait for the next frame and get the image. Times out (returning 0) after timeout seconds. The
050   * provided image will have three 3-bit channels stored in BGR order.
051   *
052   * @param image Where to store the image.
053   * @param timeout Retrieval timeout in seconds.
054   * @return Frame time, or 0 on error (call GetError() to obtain the error message); the frame time
055   *     is in 1 us increments.
056   */
057  public long grabFrame(Mat image, double timeout) {
058    return CameraServerCvJNI.grabSinkFrameTimeout(m_handle, image.nativeObj, timeout);
059  }
060
061  /**
062   * Wait for the next frame and get the image. May block forever. The provided image will have
063   * three 3-bit channels stored in BGR order.
064   *
065   * @param image Where to store the image.
066   * @return Frame time, or 0 on error (call GetError() to obtain the error message); the frame time
067   *     is in 1 us increments.
068   */
069  public long grabFrameNoTimeout(Mat image) {
070    return CameraServerCvJNI.grabSinkFrame(m_handle, image.nativeObj);
071  }
072}