Skip to content

Camera Emulation#

The Camera Emulation feature allows you to test basic camera features and create test images without having a physical camera device attached to your computer.

The camera emulation devices can be accessed using the pylon API and the pylon Viewer.

Overview#

In addition to camera transport layers like GigE Vision or USB3 Vision, pylon offers a transport layer that can create simple camera emulation devices. This allows you to develop applications without the need for a physical camera. It is also useful if you want to develop a multi-camera application and don't have enough cameras at hand.

You can create up to 256 camera emulation devices.

Besides emulating image acquisition and standard camera features, camera emulation devices also offer features that a physical camera does not offer:

Enabling Camera Emulation#

You can enable camera emulation in the pylon Viewer, in the pylon API, or both.

Installing Camera Emulation Support#

  • If you are using pylon for Linux, camera emulation support is installed by default.
  • If you are using pylon for Windows and have installed pylon via the runtime redistributable package, camera emulation support is installed by default.
  • If you are using pylon for Windows and have installed pylon via the pylon Software Suite installer:
    • If you chose the Camera User or Developer profile during installation, camera emulation support is installed by default.
    • If you chose the Custom profile during installation, camera emulation support is only installed if you selected the Camera Emulation Support option. If you haven't done that, run the installer again and select that option.

Enabling Camera Emulation in the pylon Viewer#

To enable camera emulation in the pylon Viewer:

  1. Make sure that camera emulation support is installed.
  2. In the Tools menu of the pylon Viewer, click Options.
  3. In the Options dialog, click Camera Emulation.
  4. On the Camera Emulation page, enter the desired number of camera emulation devices and click OK.
    The emulation devices will be visible in the Devices pane after a short wait.
    They can be accessed using the pylon Viewer. If you also want to access the devices in the pylon API, follow the instructions below.

Info

If the number of camera emulation devices is set to 0, the Camera Emulation node will not be shown in the Devices pane.

Enabling Camera Emulation in the pylon API#

To enable camera emulation in the pylon API:

  1. Make sure that camera emulation support is installed.
  2. Add a system environment variable named PYLON_CAMEMU and set its value to the desired number of emulation devices.
    Example: PYLON_CAMEMU=2
    This will provide two emulation devices.
    They can be accessed using the pylon API. If you also want to access the devices in the pylon Viewer, follow the instructions above.

Info

If PYLON_CAMEMU is not set or set to 0, no emulation devices will be available.

Standard Camera Features#

Camera emulation devices can emulate the following standard camera features:

Additional Features#

The following features are only available on camera emulation devices and not on physical Basler cameras.

Displaying Custom Test Images#

In addition to displaying standard test images, camera emulation allows you to display custom test images that are loaded from disk.

Info

  • On Windows, the following image file formats can be loaded: BMP, JPG, PNG, and TIF.
  • On Linux, the following image file formats can be loaded: PNG and TIF.

To display a custom test image:

  1. Set the TestImageSelector parameter to Off.
    This disables the use of standard test images.
  2. Set the ImageFileMode parameter to On.
    This enables the use of custom test images.
  3. If you want to display a single test image, provide the image file name, including the full path, in the ImageFilename parameter.
    Example: c:\images\my-test-image.png

  4. If you want to display multiple test images:

    1. Place all test images to be displayed in a single directory.
      The directory must not contain any subdirectories.
    2. Provide the full path of the directory containing the files in the ImageFilename parameter.
      Example: c:\images\

  5. Acquire at least one image to display the test image(s). If you want to display the image(s) in the pylon Viewer, click the single or continuous shot button on the toolbar.

Troubleshooting#

  • If the custom test image isn't displayed, i.e., the image displayed is completely black, then pylon couldn't load the file. Check the file name or path provided in the ImageFilename parameter. If you provided a directory name, make sure that the directory doesn't contain any subdirectories.
  • If the custom test image is displayed in monochrome, switch to a color pixel format (BGR/BGRA/RGB).
  • If the custom test image isn't displayed in full size, adjust the image ROI parameters (Width, Height, OffsetX, and OffsetY).

Generating Failed Buffers#

The Force Failed Buffer feature allows you to simulate a bad camera connection by generating failed buffers. This can be useful, e.g., to test your exception handling routines.

To generate failed buffers:

  1. Start image acquisition.
  2. Set the ForceFailedBufferCount parameter to the number of failed buffers you want to generate.
  3. Execute the ForceFailedBuffer command.
    The camera emulation device will now generate corrupt images. The number of corrupt images depends on the value of the ForceFailedBufferCount parameter.

Sample Code#

// ** Custom Test Images **
// Disable standard test images
camera.TestImageSelector.SetValue(TestImageSelector_Off);
// Enable custom test images
camera.ImageFileMode.SetValue(ImageFileMode_On);
// Load custom test image from disk
camera.ImageFilename.SetValue("c:\\images\\image1.png");
// ** Force Failed Buffer **
// Set the number of failed buffers to generate to 40
camera.ForceFailedBufferCount.SetValue(40);
// Generate 40 failed buffers
camera.ForceFailedBuffer.Execute();

INodeMap& nodemap = camera.GetNodeMap();
// ** Custom Test Images **
// Disable standard test images
CEnumParameter(nodemap, "TestImageSelector").SetValue("Off");
// Enable custom test images
CEnumParameter(nodemap, "ImageFileMode").SetValue("On");
// Load custom test image from disk
CStringParameter(nodemap, "ImageFilename").SetValue("c:\\images\\image1.png");
// ** Force Failed Buffer **
// Set the number of failed buffers to generate to 40
CIntegerParameter(nodemap, "ForceFailedBufferCount").SetValue(40);
// Generate 40 failed buffers
CCommandParameter(nodemap, "ForceFailedBuffer").Execute();

// ** Custom Test Images **
// Disable standard test images
camera.Parameters[PLCamera.TestImageSelector].SetValue(PLCamera.TestImageSelector.Off);
// Enable custom test images
camera.Parameters[PLCamera.ImageFileMode].SetValue(PLCamera.ImageFileMode.On);
// Load custom test image from disk
camera.Parameters[PLCamera.ImageFilename].SetValue("c:\\images\\image1.png");
// ** Force Failed Buffer **
// Set the number of failed buffers to generate to 40
camera.Parameters[PLCamera.ForceFailedBufferCount].SetValue(40);
// Generate 40 failed buffers
camera.Parameters[PLCamera.ForceFailedBuffer].Execute();

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
/* ** Custom Test Images ** */
/* Disable standard test images */
errRes = PylonDeviceFeatureFromString(hdev, "TestImageSelector", "Off");
CHECK(errRes);
/* Enable custom test images */
errRes = PylonDeviceFeatureFromString(hdev, "ImageFileMode", "On");
CHECK(errRes);
/* Load custom test image from disk */
errRes = PylonDeviceFeatureFromString(hdev, "ImageFilename", "c:\\images\\image1.png");
CHECK(errRes);
/* ** Force Failed Buffer ** */
/* Set the number of failed buffers to generate to 40 */
errRes = PylonDeviceSetIntegerFeature(hdev, "ForceFailedBufferCount", 40);
CHECK(errRes);
/* Generate 40 failed buffers */
errRes = PylonDeviceExecuteCommandFeature(hdev, "ForceFailedBuffer");
CHECK(errRes);

# ** Custom Test Images **
# Disable standard test images
camera.TestImageSelector.Value = "Off"
# Enable custom test images
camera.ImageFileMode.Value = "On"
# Load custom test image from disk
camera.ImageFilename.Value = "c:\\images\\image1.png"
# ** Force Failed Buffer **
# Set the number of failed buffers to generate to 40
camera.ForceFailedBufferCount.Value = 40
# Generate 40 failed buffers
camera.ForceFailedBuffer.Execute()

You can also use the pylon Viewer to easily set the parameters.