Birds Eye View - Minimal Application Integration

RidgeRun Bird’s Eye View (BEV) can be integrated directly into a custom C++ application without using the GStreamer plugin. In the minimal integration flow, your application creates a BEV engine, loads a calibration JSON file, opens the input camera using the pipelines described in that file, reads one frame from each camera, allocates the output image, and calls the processing function to generate the final top-down surround-view image. This approach is useful when you want direct API control over memory management, capture timing, and how BEV fits into a larger robotics, automotive, or embedded-vision application.

This page shows the smallest practical API flow for integrating BEV into a custom application. For setup and dependencies, see Birds Eye View/User Guide/Building and Installation. For calibration data generation, see Birds Eye View/Calibration Guide. For a pipeline-based alternative, see Birds Eye View/GStreamer/GstBEV Plugin.

Prerequisites

Before using the minimal application flow, make sure you have:

Access to the Bird’s Eye View source code and dependencies described in Birds Eye View/User Guide/Building and Installation.
A valid calibration JSON file exported from Birds Eye View/Calibration Guide.
A camera setup or input pipelines that match the calibration data.

Workflow overview

A minimal BEV application usually performs these actions in order:

Create a BEV engine instance.
Load the calibration JSON file and apply the parameters.
Open each camera or input stream defined in the calibration data.
Read one frame from each input.
Allocate the destination image buffer.
Process the input images to generate the bird’s-eye output.

Step 1

Create Birds Eye View engine:

  lp::engines::BevRectilinear<lp::RGBA<uint8_t>> bev_engine;

Step 2

Load the calibraton parameters, here input_params_file is a string with the path to the calibration.json file:

  std::vector<lp::engines::BevParams> params;
  params = lp::engines::LoadParametersFromFile(input_params_file);
  bev_engine.SetParameters(params);

Step 3

Prepare the input images, in this example the images are captured from the cameras using the GStreamer pipeline defined in the calibration file:

  num_images = params.size();
  std::vector<lp::ImageSize> src_size(num_images);
  std::vector<lp::Image<lp::RGBA<uint8_t>>> src(num_images);
  std::vector<lp::io::GStreamer<lp::RGBA<uint8_t>>> io(num_images);

  // Initialize images arrays and compute transformations
  for (unsigned i = 0; i < num_images; i++) {
    // Open the image to get the input size
    try {
      io[i].Open(io_params.cam_pipelines[i]);
    } catch (lp::Error &e) {
      std::cerr << "Error: " << e.what() << std::endl;
      return 1;
    }
    size_t src_size_pixels = io[i].GetSize().PixelCount();
    src_size[i] = io[i].GetSize();
    src[i] =
        lp::Image(src_size[i], std::shared_ptr<lp::RGBA<uint8_t>[]>(
                                   new lp::RGBA<uint8_t>[src_size_pixels]));
  }

  for (unsigned i = 0; i < num_images; i++) {
    // Reopen IO in case the stream ended
    try {
      src[i] = io[i].ReadImage();
    } catch (const lp::Error &e) {
      io[i].Open(io_params.cam_pipelines[i]);
      src[i] = io[i].ReadImage();
    }
  }

Step 4

Allocate the output images, this example assumes the same output size for all cameras:

lp::ImageSize dst_size = params[0].normalize.size;
  size_t dst_size_pixels = dst_size.PixelCount();
  lp::Image<lp::RGBA<uint8_t>> dst =
      lp::Image(dst_size, std::shared_ptr<lp::RGBA<uint8_t>[]>(
                              new lp::RGBA<uint8_t>[dst_size_pixels]));

Step 5

Finally, process the array of input images to generate the Birds Eye View output:

  bev_engine.Process(src, dst);

Related pages

FAQ

Do I need GStreamer to integrate Bird’s Eye View into my application?: No. You can integrate BEV directly through the API. GStreamer is optional and is used in this example only to read images from the camera pipelines defined in the calibration data.
What does the calibration JSON file contain?: The calibration JSON file contains the scene configuration needed by the BEV engine, including camera-related parameters and output geometry. It is generated through the calibration workflow described in Birds Eye View/Calibration Guide.
When should I use the API instead of the GstBEV plugin?: Use the API when you need tight integration into an existing application, custom memory management, or fine control over timing and processing flow. Use Birds Eye View/GStreamer/GstBEV Plugin when your system is already organized around GStreamer pipelines.
Can I use this minimal application flow on NVIDIA Jetson or NXP i.MX8?: Yes.

❯

Share This Page

Send Email Using