Teledyne DALSA 7075 Place Robert-Joncas, Suite 142 St-Laurent, Quebec, H4M 2Z2 Canada

http://www.teledynedalsa.com/mv

Sapera APF
Programmers Manual
Edition 1.01
Part number OC-SAPS-APFP0

NOTICE
2012 Teledyne DALSA Inc. All rights reserved.
This document may not be reproduced nor transmitted in any form or by any means, either electronic or mechanical, without the
express written permission of Teledyne DALSA Inc. Every effort is made to ensure the information in this manual is accurate and
reliable. Use of the products described herein is understood to be at the user's risk. Teledyne DALSA Inc. assumes no liability
whatsoever for the use of the products detailed in this document and reserves the right to make changes in specifications at any
time and without notice.

Microsoft is a registered trademark; Windows, Windows XP, Windows Vista and Windows 7 are trademarks of
Microsoft Corporation.
All other trademarks or intellectual property mentioned herein belong to their respective owners.
Released on December 4, 2012

Using the Manual

This manual exists in compiled help (CHM) andAdobe Acrobat (PDF) formats. Both formats make full use of hypertext crossreferences, and offer links to the Teledyne DALSA home page on the Internet, located at http://www.teledynedalsa.com/. Printed
versions of this manual are available upon request for a nominal fee.
Teledyne DALSA Web site contains documents, updates, demos, errata, utilities, and more.
File names, directories, function parameters are in italics (for example, xlen).
Source code, code examples, text file listings, and text that must be entered using the keyboard are in command-line style text (for
example, [PixelClock]).
Menu and dialog actions are indicated in bold text in the order of the instructions to be executed, with each instruction separated
by bullets. For example, going to the File menu and choosing Save would be written as FileSave.

Contents
Using the Manual ................................................................................................................................................................. ii
INTRODUCTION ..................................................................................................................................................................... 5
WHAT IS SAPERA APF? ................................................................................................................................................................ 5
FRAME GRABBER FUNCTIONAL BLOCK DIAGRAM ....................................................................................................................... 7
Sapera APF Function Library .............................................................................................................................................. 8
SAPERA APF CONCEPTUAL DIAGRAM.......................................................................................................................................... 9
SUPPORTED HARDWARE ............................................................................................................................................................. 10
WHAT DOES SAPERA APF INSTALLATION INCLUDE? ................................................................................................................. 10
WHAT ELSE IS REQUIRED? .......................................................................................................................................................... 10
SAPERA APF QUICK START GUIDE ................................................................................................................................ 11
REQUIRED SOFTWARE ................................................................................................................................................................ 11
SYSTEM REQUIREMENTS ............................................................................................................................................................ 11
INSTALLATION ............................................................................................................................................................................ 11
USING THE SAPERA LICENSE MANAGER..................................................................................................................................... 14
CREATING A SIMPLE DESIGN AND FIRMWARE IN SAPERA APF .................................................................................................... 14
EVALUATING THE FIRMWARE ON THE XCELERA-CL VX4 .......................................................................................................... 18
USING SAPERA APF ............................................................................................................................................................. 21
Starting a Sapera APF Design ........................................................................................................................................... 21
APPLICATION GUI ...................................................................................................................................................................... 23
Program Window ................................................................................................................................................................ 24
What is a Function? ............................................................................................................................................................ 25
Inserting Functions ............................................................................................................................................................. 26
Function Properties ............................................................................................................................................................ 27
Connecting Functions ......................................................................................................................................................... 28
Link Properties ................................................................................................................................................................... 30
Creating Function Groups.................................................................................................................................................. 33
VALIDATING A DESIGN ............................................................................................................................................................... 34
DESIGN SIMULATION .................................................................................................................................................................. 34
PLACING AND ROUTING A DESIGN.............................................................................................................................................. 36
Resource Utilization ........................................................................................................................................................... 37
SAVING ....................................................................................................................................................................................... 38
APPLICATION SETTINGS ............................................................................................................................................................. 39
TESTING THE FIRMWARE USING THE RTPRO DEMO ................................................................................................................... 40
Loading Sapera APF Firmware ......................................................................................................................................... 40
Using the VX4 RTPro Demo ............................................................................................................................................... 41
KEY CONCEPTS .................................................................................................................................................................... 43
Tap reordering and pixel packing ...................................................................................................................................... 43
Flow control ....................................................................................................................................................................... 46
Multiple outputs (non-merged parallel branches) .............................................................................................................. 47
Estimating a designs data throughput ............................................................................................................................... 49
Parallelism ......................................................................................................................................................................... 51
Merged parallel branches................................................................................................................................................... 53
Using Kernels ..................................................................................................................................................................... 57
Color Processing ................................................................................................................................................................ 61
Using Buffers ...................................................................................................................................................................... 63
Recursive Functions ........................................................................................................................................................... 64
Changing image dimensions ............................................................................................................................................... 65
Using signals ...................................................................................................................................................................... 67

Sapera APF Programmer's Manual

Contents i

USING SAPERA APF FIRMWARE ..................................................................................................................................... 73

CONFIGURING PARAMETERS ....................................................................................................................................................... 73
CONFIGURING TRANSFERS .......................................................................................................................................................... 74
SAPERA APF INTRODUCTORY EXERCISES ................................................................................................................. 77
EXAMPLE DESIGNS ..................................................................................................................................................................... 77
AUTO GAIN ................................................................................................................................................................................ 79
AUTO-THRESHOLD ..................................................................................................................................................................... 80
BAYER ........................................................................................................................................................................................ 81
CC1 VARIABLE PERIOD AND VARIABLE WIDTH......................................................................................................................... 81
COLORSEGMENT ........................................................................................................................................................................ 82
EXTERNAL FRAME TRIGGER ....................................................................................................................................................... 83
EXTRACTKERNEL ....................................................................................................................................................................... 83
FLAT LINE CORRECTION ............................................................................................................................................................. 84
FRAME DIFFERENCE ................................................................................................................................................................... 85
GPI SELECT PROCESSING PATH .................................................................................................................................................. 86
GPI TO CC1 ............................................................................................................................................................................... 86
GAUSSIAN5X5 ............................................................................................................................................................................ 87
JPEG RBG ................................................................................................................................................................................. 88
LOSSLESS COMPRESSION ............................................................................................................................................................ 89
MEDIAN FILTER .......................................................................................................................................................................... 89
MEDIAN PIXEL REPLACEMENT ................................................................................................................................................... 90
MORPH CLOSE ............................................................................................................................................................................ 90
MORPH DILATE .......................................................................................................................................................................... 91
MORPH EDGE DETECTION .......................................................................................................................................................... 91
MORPH ERODE ........................................................................................................................................................................... 92
MORPH OPEN ............................................................................................................................................................................. 92
MULTIPLE OUTPUTS ................................................................................................................................................................... 93
PASS THROUGH .......................................................................................................................................................................... 93
READ/WRITE GENERAL PURPOSE IOS ........................................................................................................................................ 94
RECURSIVE AVERAGE ................................................................................................................................................................ 94
SATURATION DETECTION ........................................................................................................................................................... 95
SIGNAL TO PIXEL ....................................................................................................................................................................... 96
SIMPLE BUFFER DDR ................................................................................................................................................................. 97
SIMPLE BUFFER RLDRAM ........................................................................................................................................................ 97
SIMPLE PROCESSING ................................................................................................................................................................... 97
SIMPLE THRESHOLD ................................................................................................................................................................... 98
SOBEL EDGE ............................................................................................................................................................................... 99
SUBSAMPLED PROCESSING ....................................................................................................................................................... 100
SYNC MEMORY BANKS ............................................................................................................................................................ 100
SYNC VARIABLE LATENCY ....................................................................................................................................................... 101
SYNC VARIABLE LATENCY IMPROVED ..................................................................................................................................... 102
VARIABLE OUTPUT DIMENSIONS .............................................................................................................................................. 103
WHITE BALANCE ...................................................................................................................................................................... 103
YUV PROCESSING .................................................................................................................................................................... 104
SAPERA APF REFERENCE ............................................................................................................................................... 105
BOOLEAN FUNCTIONS .............................................................................................................................................................. 106
Boolean Function Library ................................................................................................................................................ 106
COLOR FUNCTIONS ................................................................................................................................................................... 118
Color Function Library .................................................................................................................................................... 118
DATAREDUCTION FUNCTIONS .................................................................................................................................................. 130
DataReduction Function Library ..................................................................................................................................... 130
DIRECTIVES FUNCTIONS ........................................................................................................................................................... 135
Directives Function Library ............................................................................................................................................. 135
GEOMETRY FUNCTIONS ............................................................................................................................................................ 138
Geometry Function Library .............................................................................................................................................. 138
IMAGE I/O FUNCTIONS ............................................................................................................................................................. 140
Image I/O Function Library ............................................................................................................................................. 140
KERNEL FUNCTIONS ................................................................................................................................................................. 147
Kernel Function Library ................................................................................................................................................... 147
MATH FUNCTIONS .................................................................................................................................................................... 156
Sapera APF Programmer's Manual

Contents ii

Math Function Library ..................................................................................................................................................... 156

MEMORY FUNCTIONS ............................................................................................................................................................... 166
Memory Function Library ................................................................................................................................................ 166
PIXELCONTROL FUNCTIONS ..................................................................................................................................................... 169
PixelControl Function Library ......................................................................................................................................... 169
SIGNAL I/O FUNCTIONS ............................................................................................................................................................ 179
Signal I/O Function Library ............................................................................................................................................. 179
STATISTICS FUNCTIONS ............................................................................................................................................................ 203
Statistics Member Functions............................................................................................................................................. 203
STREAMCONTROL FUNCTIONS ................................................................................................................................................. 215
StreamControl Function Library ...................................................................................................................................... 215
APPENDIX: INSTALLATION AND LICENSING ........................................................................................................... 241
SYSTEM REQUIREMENTS .......................................................................................................................................................... 241
INSTALLATION .......................................................................................................................................................................... 241
Additional Installation Requirements ............................................................................................................................... 242
LICENSING ................................................................................................................................................................................ 242
What is a license? ............................................................................................................................................................. 242
Licensing Errors ............................................................................................................................................................... 243
CONTACT INFORMATION ............................................................................................................................................... 247
SALES INFORMATION ................................................................................................................................................................ 247
TECHNICAL SUPPORT ............................................................................................................................................................... 248
GLOSSARY OF TERMS ...................................................................................................................................................... 249
INDEX .................................................................................................................................................................................... 251

Sapera APF Programmer's Manual

Contents iii

Sapera APF Programmer's Manual

Contents iv

Introduction
What is Sapera APF?
Sapera APF is a software application for programming Teledyne DALSA frame grabbers to perform image processing
algorithms. By offloading some or all of the image processing to the frame grabbers FPGA , image processing algorithm
performance can be improved greatly compared to performing the same operations using the host computer CPU.
Field programmable gate arrays (FPGAs) are digital integrated circuits that contain configurable (programmable) blocks of logic
along with configurable interconnects between these blocks. FPGAs typically run at a lower frequency than CPUs but
compensate by being massively parallel.
FPGAs are currently used by Teledyne DALSA frame grabbers to package the data input from the camera, according to the
cameras configuration and protocol (for example, CameraLink), in what is frequently called the Front End. The frame grabber
then outputs the acquired frames over the required interconnect to the host computer (for example, PCIe or GigE), using what is
frequently called the Back End.

When you update the firmware on one of Teledyne DALSA frame grabbers, you are actually loading a design into its FPGA.
Using Sapera APF, user-defined processing can be performed on the FPGA. Most types of image processing operations can be
performed on the FPGA such as thresholding, image morphology, filtering, color conversions, motion detection, blob analysis,
and so forth.
Benefits of using the on-board FPGA include:
Improved maximum bandwidth;
Reduced CPU usage: allows systems to be more responsive and lets them run more complex algorithms;
FPGA can react upon and/or drive I/O signals with very precise timings;
On-board data reduction can improve utilization of PCI-Express bus and let the host CPU processing selected parts of the
images or store compressed images for later processing.
Sapera APF provides a graphical user interface that allows users to construct an FPGA image processing chain from input to
output using a set of configurable image processing functions. It does not require any knowledge of FPGA programming by a
hardware description language (for example, VHDL or Verilog).
After functions are placed into a design and connected, the design can be validated and simulated, with the possibility of
displaying the result of each step. A graphical representation of the design is also generated, providing a visual representation of
the image processing flow. The simulated output of each function can also be displayed to provide quick feedback of the expected
results of the algorithm being designed. This allows the building of a complete image processing algorithm step-by-step, where all
intermediate images can be validated and parameters can be fine-tuned to get optimal results.

Sapera APF Programmer's Manual

Introduction 5

When the design is completed, it is compiled into a set of firmware files which contains information that will be uploaded into the
FPGA to program it to perform the specified functions. To perform this task, Sapera APF invokes and handles all interactions
with the Xilinx ISE tools (purchased and installed separately). No experience with Xilinx ISE tools is required but a text output is
provided containing information for those with FPGA experience.
The firmware files can be loaded to the target frame grabber using the Sapera Device Manager tool. After the frame grabber has
been updated, it can be tested using the RTPro Demo installed with Sapera APF. This application allows quick configuration of
firmware with custom processing without writing a single line of source code. This is made possible by the flexible and selfdocumented approach used for firmware generated by Sapera APF.
Note that the source code to the RTPro Demo is provided in the Sapera APF documentation as a possible starting
point for your own application.
Many Sapera APF functions contain configurable parameters which can be modified at run-time using the feature access
functions of Sapera LT (in particular, the SapAcqDevice class). For example, a threshold value for a Sapera APF function in an
FPGA design can be modified by an application, by using the Sapera LT API. Please refer to the Using Sapera APF Firmware
section for more details.

Sapera APF Programmer's Manual

Introduction 6

Frame Grabber Functional Block Diagram

The following diagram presents an overview the essential frame grabber components, in particular the Teledyne DALSA XceleraCL VX4.

Xcelera-CL VX4
Functional Block Diagram
Image memory banks.
Used for storing
intermediate images and
results. Multiple memory
banks permit concurrent
operations for higher
performance.

Image Buffer
512MB

Bank 0

Bank 1

Bank 2

Bank 3

Bank 4

DDR
512MB

RLD
32MB

RLD
32MB

RLD
32MB

RLD
32MB

ACU
Control

GPO
DMA_in

Sapera APF User Design

64-bit

64-bit

64-bit

64-bit

DMA_o_3

DMA_o_2

DMA_o_1

DMA_o_0

CC
(default)

Fully CameraLink
compliant, supports CC
lines control from either
FG or the user code.

CC

CC

64-bit

4
GPI

Select

Data

(Acquisition Control Unit)

CC
Selector

Camera Link
Base/Medium/Full/Deca modes

Used for camera

control, trigger and
shaft encoder input.

General purpose
inputs/outputs are
user accessible.

Connector

Image from the camera. The

ACU buffers incoming images
and presents to them to the
user code on demand. Use
Sapera LT and CamExpert to
create camera configuration
file.

Output processed
images and results
concurrently using
multiple output paths
to the host application.
User FPGA
Space

PCIe Interface
PCIe
x4

HOST

Sapera APF Programmer's Manual

Introduction 7

Sapera APF Function Library

The Sapera APF library includes a variety of logic, image processing, memory, and IO functions, which are organized into
functional groups.
Functional Group
Image I/O
Memory
Stream Control

Pixel Control
Boolean
Math
Kernel
Color
Statistics
Geometry
DataReduction
Directives
Signal I/O

Description
Functions for connecting the user design to the frame grabbers front-end and back-end. Essentially,
these functions are used to establish the design connection from the camera to the host PC.
Functions for accessing FPGA DDR and RLDRAM memory banks. Depending on the design,
buffering of images or data may require these memory resources.
Functions for manipulating the image data stream in the user design. These functions are used to
control the flow of data through the design by creating branches, synchronizing streams, changing
the stream size (bit width), and so forth.
Functions for manipulating the image stream at the pixel level, such as keeping the most or least
significant bits, extracting pixel coordinates, as well as other operations.
Functions for implementing boolean logic on the image or data stream. Functions can be used to
perform thresholding, comparisons, and other logic operations.
Functions for mathematical operations such as multiplication, division, subtraction, as well as for
implementing look-up tables (LUTs) and bit shifting.
Functions for implement morphological operations using preset or user-defined kernels of variable
size.
Functions for performing color conversions between color formats, splitting and merging color
components, and white balancing.
Functions for providing image statistics such as a histogram, vertical/horizontal minimums and
maximums, and others.
Functions for subsampling images up or down.
Functions for performing data reduction, such as Huffman encoding, JPEG compression, Paeth
filtering, and run-length encoding.
Functions for changing the color format, image dimensions, sign of the data, as well as other
operations.
Functions for accessing the frame grabber inputs and outputs, generating signals and clocks, and
camera control signals.

Sapera APF Programmer's Manual

Introduction 8

Sapera APF Conceptual Diagram

The following diagram presents an overview of how Sapera APF interacts with a frame grabber, in particular the Teledyne
DALSA Xcelera- CL VX4.

Sapera APF Conceptual Diagram

The Memory library
functions FrameBuffer
and LineBuffer functions
are used to access the
image memory banks.

Image Buffer
512MB

Bank 0

Bank 1

Bank 2

Bank 3

Bank 4

DDR
512MB

RLD
32MB

RLD
32MB

RLD
32MB

RLD
32MB

32bit

32bit

32bit

32bit

Logical
bus width.

DMA_in

64-bit

Select

CC

CC

FrameOut
Raw

FrameOut
2

FrameOut
3

GPO

GPIOs

4
GPI

FrameOut
4
64-bit

64-bit

DMA_o_3

DMA_o_2

DMA_o_1

DMA_o_0

The Image I/O functions connect the

user design with the frame grabbers
front and back ends. The image
format at the FrameOutRaw function
must be the same as the CameraIn
function. Other frame outputs can
have other formats.

User image
processing design
implemented with
Sapera APF functions.

64-bit

64-bit

CC
(default)

The Signal I/O library

CC1, CC2, CC3, and
CC4 functions are
used to access the
camera control
signals.

CameraIn

Data

(Acquisition Control Unit)

Control

CC
Selector

Camera Link
Base/Medium/Full/Deca modes

128bit

ACU

Connector

The Camera Link front-end

image format is set in the
main program properties
of Sapera APF.

The Signal I/O library

GPI0 GPI3 and GPO0GPO3 functions are used
to access the frame
grabber inputs and
outputs.

User FPGA
Space

PCIe Interface
PCIe x4

HOST

Sapera APF Programmer's Manual

Introduction 9

Supported Hardware
Currently, Sapera APF designs can be used with the Teledyne DALSA Xcelera- CL VX4 frame grabber. For more information,
refer to the Xcelera VX4 documentation.
Future support for other frame grabbers and acquisition devices is possible.
Sapera APF can be used to design an image processing application without having the actual target hardware
installed on the host system.

What does Sapera APF Installation Include?

The Sapera APF installation includes the following:
Sapera APF tool
Sapera Essential
Documentation
Example designs
Teledyne DALSA License Manager
VX4 RTPro Demo
USB license dongle and license file (sent by email upon purchase)
For the complete installation procedure, refer to to the Sapera APF Quick Start Guide document included with the Sapera APF
installation, as well as the Appendix: Installation and Licensing in this document.

What else is required?

For synthesis of FPGA firmware:
Xilinx ISE, version 10.1 Service Pack 3 (SP3) and higher
For using the FPGA firmware:
Teledyne DALSA Xcelera-CL VX4 board
Xcelera-CL VX4 driver 1.10 and higher
Sapera LT 7.20 and higher

Sapera APF Programmer's Manual

Introduction 10

Sapera APF Quick Start Guide

The following tutorial guides you through all steps required for quick testing and evaluation of Sapera APF. It covers:
Required Software
System Requirements
Installation
Using the Sapera License Manager
Creating a simple design and firmware in Sapera APF
Evaluating the firmware on the Xcelera-CL VX4

Required Software
From Teledyne DALSA:
To design and synthesize Xcelera-CL VX4 firmware:
Sapera APF 1.0
To test the firmware:
Xcelera-CL VX4 device drivers, version 1.10
Sapera LT 7.20, or higher
A suitable Camera Link camera.
From Xilinx:
Xilinx ISE (Logic Edition), version 10.1 SP3 and higher. This set of tools may be purchased by contacting Xilinx
directly.

System Requirements
Sapera APF runs under either 32-bit or 64-bit version of Windows.
Minimum system hardware requirements:
4 GB of RAM
25 GB free space on hard drive
A high performance CPU is recommended; the recent Xilinx ISE tools (version 13 and above) can run faster on
multi-core CPUs.

Installation
To test the firmware created by Sapera APF, an Xcelera-CL VX4 frame grabber is required on the host system. Refer to the
Xcelera-CL VX4 documentation for complete installation instructions.
1- Installing the Xcelera-CL VX4 device driver
The Xcelera-CL VX4 device driver installation requires an update of the boards firmware. Click Manual to select which
firmware to use.

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 11

The Xcelera-CL VX4 device driver installs a number of firmware files that each target a specific set of cameras depending on
their tap configuration. The Xcelera-CL VX4 does not have a generic Camera Link front-end that handles all cameras; instead a
set of specific front-ends is provided for each Camera Link tap configuration. This is done to reserve more FPGA resources for
custom processing.
In the Device Manager/Update Firmware tool, you can select which firmware to load depending on your camera. Clicking Start
Update will send the firmware file to the Xcelera-CL VX4 boards flash memory where it will be used every time the board is
reset.

After the Xcelera-CL VX4s firmware has been updated, use the Sapera CamExpert tool to setup the camera and create a
camera configuration (.CCF) file that saves camera parameter settings; this file will be used later in this tutorial. CamExpert
is included with Sapera LT and is available from the Windows start menu at Teledyne DALSA Sapera LT . CamExpert.
For more information on using CamExpert to generate .CCF files refer to the Sapera LT documentation or the CamExpert
applications help file.
2- Installing Sapera APF
Installation of Sapera APF also installs the Sapera License Manager (see Using the Sapera License Manager below). Verify that
the license dongle is not plugged into a USB port when installing Sapera APF as this may interfere with the installation of the
required device drivers.
3- Installing Xilinx ISE
The Xilinx ISE tools can be installed before or after Sapera APF; the installation order is not important. However, Sapera APF
must be able to access the Xilinx ISE tools to perform a designs place-and-route operation. To validate the Xilinx ISE
installation, verify that the Xilinx tools can be accessed from the command line; open a Command Prompt window and type this
command:
C:\>bitgen.exe
If the error bitgen.exe is not recognized as an internal or external command is returned, modify the Windows Path
environment variable to include the location of the appropriate Xilinx executables. Some Xilinx installations do this
automatically, for other versions it must be done manually.
To edit the Windows System variables
1- Open the Control Panel System and Security System window and click on Advanced system settings:
Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 12

2-

Click on Advanced tab, then on Environment Variables:

This will open the Environment Variables dialog. One of the System variables should be Path; this is where the path to the
Xilinx tools is added. For example, with Xilinx ISE 13.4 in the default installation directory, the following path must be added to
the Path system variable (separated from other entries using a ;):
C:\Xilinx\13.4\ISE_DS\ISE\bin\nt\

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 13

Using the Sapera License Manager

The purchase of Sapera APF includes the following licensing materials:
USB dongle
License file (.LIC file) (sent by email upon purchase)
The .LIC file, when used with the USB dongle, contains a license valid for all (or most) Sapera Processing tools as well as Sapera
APF. A license is only valid if the USB dongle is connected and the computers local license was initialized using the Sapera
License Manager (automatically installed with Sapera APF).
The Sapera License Manager handles all Sapera licenses (that is, Sapera APF and Sapera Processing). It can be started through
the Windows Start Menu under Teledyne DALSA Sapera License Manager.
In the License Manager, click on Load Single License and browse for the .LIC file. The product license state is shown as License
OK in green for all enabled tools.
Note that if the USB dongle is moved to a different computer (where Sapera APF was also installed), the License
Manager must be run on this computer as well to initialize its local license. Therefore, it is important to retain the
.LIC file that is sent by email upon purchase of Sapera APF.

For more information on licensing, refer the Appendix: Installation and Licensing.

Creating a simple design and firmware in Sapera APF

When Sapera APF starts, it shows the Design Manager window that is used either to load a previously-generated design or to start
a new design. To create a new design you can browse for the previously-generated .CCF file, and determine the new designs
name.

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 14

When a new design is created Sapera APF will take a few seconds to retrieve the necessary information, then the default initial
design is shown:

Instructions on how to design FPGA designs with Sapera APF are available in the Using Sapera APF, Key Concepts and Sapera
APF Introductory Exercises sections. This tutorial demonstrates how to create a very simple design that does pixel inversion onboard the Xcelera-VX4s FPGA. This is done through the following steps:
1- In the Program window, click on Add function. The list of functions which are available is displayed. For the current
example, select the function BitwiseNot in the Boolean library.

At this point there are two functions which have been instantiated in the design:
a. CameraIn: this function represents the incoming data from the camera.
b.

BitwiseNot: this function inverts all the bits of the pixel values it receives, and then outputs the resulting pixel
values.

2- The connection between the functions can now be made. The CameraIn function has a single output (appropriately called
CameraIn.Out). Click on Select destination to indicate to Sapera APF which function will receive the data generated
by the CameraIn function. In the current design the only function available is the BitwiseNot function.

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 15

3- After the connection is made, the designs diagram is updated to show the connection. The next step is to send the
processed pixel values to the host computer through efficient DMA transfers. This is done with any of the FrameOut
functions from the Image I/O library. The FrameOutRaw function allows testing of the firmware using the standard
Sapera LT applications (for example, CamExpert, Grab Demo, and so forth). Add a FrameOutRaw function to the
design, then make the connection between BitwiseNot.Out and FrameOutRaw.In:

4- Click on the various elements in the Program window to see the related properties. When clicking on the CameraIn
function, the functions properties are displayed in the Property window. Each function has different properties; these are
documented in the Sapera APF Programmers Manual. For example, the CameraIn functions properties include the
following:

For the CameraIn function, the default setting of its LinkFormat property is set to gray8x8 which indicates that it outputs 8 pixels
at a time (per FPGA design clock), and that those pixels are gray-scale with 8 bits of precision. There are also parameters to
indicate the maximum dimensions of the images that will be grabbed from the camera. These parameters are used by Sapera APF
to make sure enough FPGA resources are allocated to process whole images. To make sure FPGA resources are not uselessly
wasted, it is advisable to set these parameter values (especially the MaxFrameWidth) to the image dimensions used in the final
application.
Click on the CameraIn.Out link to see how the data is transferred at the output of the CameraIn function:
Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 16

The data link transfers 8 pixels per clock, each pixel being monochrome with 8 unsigned bits of precision. We can compute the
maximum bandwidth that can be transmitted on this link, for a FPGA running at 100 MHz:
(8 pixels per clock) x (1 byte per pixel) x (100 MHz) = 800 MB/s
The maximum image dimensions that can be transferred on this data link are also displayed. If the MaxFrameWidth and
MaxFrameHeight parameters of the CameraIn function are changed, the same values are propagated on the output link.
You can also click on the FrameOutRaw function to see its parameters. These parameters are described in detail in the Sapera
APF Programmers Manual. For the current design, please set the value of PeriodicSendNumFrames to 1.
5- To validate the processing, Sapera APF can perform a quick bit-accurate software simulation of the processing being
designed. This software simulation is done directly within Sapera APF and is much faster than traditional cycle-accurate
simulation such as done using FPGA design tools. Clicking on the Simulation tab at the bottom of Sapera APF shows
which file is used to emulate the output of the camera, as well as a list of intermediate points in the design which can be
monitored.
a.

Click on CameraIn.Out Browse to select an input image. Sample image files are distributed with Sapera
APF under the directory \Images.

b.

Check the BitwiseNot.Out checkbox to enable monitoring this link.

c.

In the menu at the top of Sapera APF, click on DesignSimulate. Sapera APF will create a window that shows
the images at every point in the design that was enabled in the simulation.

6- After a design is created and validated, Sapera APF can synthesize the design into a firmware file that will run on the
Xcelera-CL VX4s FPGA. To start this step, click on DesignPlace & Route. Sapera APF automatically starts the
Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 17

Xilinx tools to perform all required tasks. No knowledge of FPGA programming is required. The output of the Xilinx
tools is displayed in the Output Messages window. This process should take around 15 minutes for a simple design,
depending on the speed of the host computer. For complex designs it may take the Xilinx tools more than one hour to
complete.

Evaluating the firmware on the Xcelera-CL VX4

After Sapera APF has completed the synthesis process, a message box displays if the process was successful or not. Place and
route may fail if the design is too complex for the resources available on the FPGA; however, for this tutorial, inverting pixel
values is a simple processing task and it should run successfully. The path of the output files is displayed in the Output Messages
window. This directory contains 4 files that have been created: one .CBF file, one .XML file and two .CBG files. Use the Device
Manager to load the firmware (.CBF) into the Xcelera-CV VX4. The Device Manager can be started from Windows Start Menu,
under Teledyne DALSAX64 Xcelera-CL VX4 Device Driver.
To load firmware:
1. Click the Device Info tab.
2. Click the Firmware tab.
3. Browse for the firmware file.
4. Click Program.
5. Click Reset.

When browsing for the firmware file, select the .CBF file that was generated by Sapera APF. The .CBF file can then be loaded
into the boards flash memory where it will be used when the board is reset (that is, when the computer boots up). The XceleraCL VX4 expects to find the .XML and .CBG files in the same directory where the .CBF was taken; therefore, if the files are
moved, use the Device Manager again to select the .CBF file at the new location.

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 18

After the Xcelera-CL VX4 has been updated with the newly generated firmware, use the VX4 RTPro Demo to test it. It can be
started from Windowss Start menu, under Teledyne DALSA Sapera APF VX4 RTPro Demo (32-bits or 64-bits depending
on your computer). When using the demo, the first step is to select the CCF camera configuration file you created in step 1
(Installing Xcelera-CL VX4 device driver):

The VX4 RTPro Demos interface has multiple sections:

1. Acquisition control: grabbing from the camera is initiated and stopped here.
2. Transfer control: output DMAs (from the VX4s FPGA to the host computers memory) can be individually enabled.
Since the simple inversion design has a single output it is the only output that is enumerated.
3. Buffer information: Sapera APF will automatically allocate memory buffers with appropriate dimensions and format to
receive data from the FPGA. The buffers configuration and their time stamp (when data has been received from the
FPGA) are displayed.
4. Processing parameters: the .XML file generated by Sapera APF is a GenICam-compliant description of the various
parameters of the firmware, and also includes all the information required to describe the various outputs. Since the
simple inversion design contains no processing parameters, all that is displayed is the information describing the outputs.
5. Transfer information: the Trigger-to-Image Reliability framework of Teledyne DALSA provides information about the
ongoing transfers to ensure that no images have been lost without notification to the application,
6. Image display: displays the last image received from the VX4. If multiple outputs have been enabled, they can be
selected through the Display drop-down list. The mouse wheel can be used to zoom-in on specific portions of the image.
Note that after the Grab button has been pressed, it may be required to click on the Use mouse wheel to zoom button to
let the demo use the mouse wheel.
7. Reset: this will trigger a low-level hardware reset of the Xcelera-CL VX4. All parameter values will revert to their
initial default state.

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 19

Sapera APF Programmer's Manual

Sapera APF Quick Start Guide 20

Using Sapera APF

The typical steps involved in creating a Sapera APF design are:
1. Launch Sapera APF
2. Start a new design, selecting the required camera front-end manually or using an existing camera configuration file.
3. Add functions to perform processing and output results
4. Connect the functions
5. Set parameter values
6. Validate the design
7. Simulate the design
8. Place and route the design
9. Use the frame grabber Device Manager application to load the resulting .cbf FPGA firmware file.
10. Use the RTPro Demo to configure and use the firmware design loaded into the frame grabbers FPGA.
Steps 4 to 7 will typically be repeated several times until satisfactory results are obtained in the simulation. In general, it is
recommended that the design be tested using simulation before starting the generation of the FPGA firmware since the place and
route operation can take a relatively lengthy amount of time; from several minutes to a few hours, depending on the complexity of
the design and the speed of the development computer.

Starting a Sapera APF Design

When Sapera APF is started, or when selecting FileNew in Sapera APFs top menu, the Design Manager window appears:

The Design Manager allows two options:

1.

Open an existing design. Sapera APFs designs are saved as files with an .apf extension. A number of example designs
are located in the \Designs\Example directory of the Sapera APF installation.

2.

Create a new design. When creating a design, the custom processing functionality designed in Sapera APF in the frame
grabbers FPGA includes a standard, thoroughly-tested functionality for grabbing images from a Camera Link camera.
There are a number of options for this standard Camera Link front-end, depending on the tap configuration of the
camera. There are two methods for selection this front-end:
a.

Select a .ccf camera configuration file. Camera configuration files are generated by Sapera LTs CamExpert
tool. The best method for generating .ccf files is to first update the frame grabber with one of the standard
firmware shipped with its driver package. CamExpert can then be used to configure and validate the camera,
and to save the resulting .ccf file. For more information, refer to the Sapera LT and frame grabber documention.

b.

Select the Camera Link front-end directly. Unchecking the Determine using camera configuration file
checkbox enables the Camera Link front-end list box.

Before a new design can be created, it must be given a name. When that design is later saved, its file name will be the design
name, appended with the .apf extension. By default, the output firmware files are located under Windows Shared Documents
directory. For example under Windows 7, the output files are located under:
C:\Users\Public\Documents\Teledyne DALSA\Firmwares\ DESIGN_NAME

Sapera APF Programmer's Manual

Using Sapera APF 21

If output files are being generated and the DESIGN_NAME output folder already exists, a new folder will be created with an
incrementing index appended, for example, DESIGN_NAME_1, DESIGN_NAME_2, and so forth. This prevents overwriting
previous firmware files.
When a design is created, it contains the typical starting point: the Image I/O::CameraIn function to receive images from the
camera. If the design is created by selecting a .ccf camera configuration file, the Image I/O::CameraIn parameters
MaxFrameWidth and MaxFrameHeight are set to the dimensions described in the .ccf file.

Sapera APF Programmer's Manual

Using Sapera APF 22

Application GUI
The Sapera APF application window is designed to facilitate the development environment.

All the various panels can be enabled or disabled from the View menu.

Sapera APF Programmer's Manual

Using Sapera APF 23

Program Window
The Program window is the work area where the FPGA design is assembled. It is a tree view showing a number of nodes.
Clicking on a given node displays the nodes properties in the Property panel.
There are four different types of nodes:
1. Main: this is the root of the tree, containing global properties like the designs name.
2. Functions: these are the data processing elements. All functions have a number of input and output ports, and a number
of properties depending on the function.
3. Inputs/Outputs: some functions can have a variable number of input and/or output ports, those can be changed by
clicking on the functions Input or Output nodes.
4. Links: the properties of those nodes describe how the data is being transferred between functions.

Sapera APF Programmer's Manual

Using Sapera APF 24

What is a Function?
In the mathematical sense, a function is a relationship that for a given input establishes the related output. In Sapera APF,
functions are basic processing elements, each with a number of inputs and a number of outputs.
For users without FPGA experience it is worthwhile to mention the fundamental difference between a function running on a CPU
and the equivalent function running on the FPGA. A good example of equivalent functions is Sapera Processings function
CProBasic::Invert, and Sapera APFs function Boolean::BitwiseNot

Both functions perform the same operator (all bits of input pixel values are inverted) and so will give the same results, but they
will execute in a different manner:
CPU:

When CProBasic::Invert is called it is given a complete image residing in the CPUs memory;

During a brief period of time, the whole CPU is busy computing the Invert function;

Resulting image is output back to memory, where it can be recuperated by the next function.

FPGA:

What the Boolean::BitwiseNot function receives is not a whole image at once, but a stream of incoming pixels.

The implementation of the Boolean::BitwiseNot function will be done by a physical circuit somewhere inside the FPGA
that has been configured to compute the Boolean:Not operation. During the whole time an image is being processed,
only a small portion of the FPGA is busy computing the Boolean:Not function.

After the pixel values have been inverted by the Boolean::BitwiseNot function, they are placed at the output of the circuit
inside the FPGA where they can be used by the next function.

The major differences between the CPU and FPGA can be summarized as follows:
Difference 1:

On the CPU, a functions results are available only once a whole image has been processed. The CPU can be thought of
as an image processor.

On the FPGA, each function outputs resulting pixels as soon as they are computed. The FPGA can be thought of as a
pixel processor.

Difference 2:

On the CPU, the amount of processing that can be done is limited by the amount of time available to do the processing.

On the FPGA, the amount of processing that can be done is limited by the amount of FPGA resources available to do the
processing.

Difference 3:

On the CPU, it does not matter in what order the output pixels are computed, since it is the final resulting image that is
passed to the next function. All that matters is that the functions output image is valid once the processing has been
completed.

On the FPGA, care must be taken so that the function outputs pixels in the same order and format as is expected by the
next function.

Difference 4:

On the CPU, typically the resulting pixels must be aligned to typical memory boundaries, that is 1, 2 or 4 bytes. Pixels
with precision of 10 bits per pixel will occupy 2 bytes of memory.

On the FPGA, output pixel values are more configurable. Pixels with precision of 10 bits per pixel will occupy just the
amount of FPGA resources required for 10 bits.

Sapera APF Programmer's Manual

Using Sapera APF 25

Inserting Functions
Functions are added to the program by clicking F() Add Function to add a function at the end of the program or or the
symbol to insert a function inside the program.

A Sapera APF design always begins using an Image I/O::CameraIn function, and typically ends using at least one of the Image
I/O::CameraIn function.
Functions are organized by type using a directory.

For example, the Kernel folder contains the available image processing Kernel functions. Detailed descriptions of all the functions
are available in the Sapera APF Reference section of this manual. To add a function to the program, simply click on the function.

Sapera APF Programmer's Manual

Using Sapera APF 26

Function Properties
The Properties panels displays the available parameters for the selected function. Each function may have a number of individual
parameters that can be configured in the Properties window.
For example, the Boolean::GreaterOrEqualVal function implements a thresholding operation. If the input pixel is higher or equal
than a certain threshold value, it will output a single bit with value 1; otherwise, it will output a single bit with value 0. This
threshold value is the Number parameter of the function:

Another example is the Image I/O::FrameOutRaw functions LinkFormat parameter. This parameter determines the type of pixel
data expected by the FrameOutRaw function at its input:

Some functions are configured through properties of their output links (see the Connecting Functions for description of links).
For example, the Kernel::KernelCreate function will operate depending on the KernelWidth and KernelHeight paramters of its
output link. In the following example, the KernelCreate is configured to output 7x7 kernels (see the Using Kernels section for
more details):

Sapera APF Programmer's Manual

Using Sapera APF 27

Some parameter values can be changed after the firmware has been generated, while others cannot:

Non run-time changeable (static) parameters cannot be changed after the FPGA compilation process. For example,
the previously described LinkFormat, KernelWidth and KernelHeight parameters must be set during the design process
because they affect how the FPGA firmware will be structured.

Run-time changeable (dynamic) parameters can have a default value set during the design process, but can be
modified at runtime. Using Sapera LT, dynamic parameters are available as part of the feature list accessible from the
SapAcqDevice object representing the onboard FPGA firmware, and can be modified using the
SapAcqDevice::SetFeatureValue function. Refer to the Sapera LT documentation for more information on accessing
features using the Sapera LT API.

To determine if a parameter can have its value changed at run-time, refer to the Sapera APF Reference section of this manual.
Every function has a default Name parameter which can be changed for a more descriptive title depending on the application.
When the name is modified, the original function name is shown in brackets in the design diagram. For example, when the
GreaterThanVal function is used to perform a thresholding operation, the parameter name can be changed to Threshold to make
the design flow easier to follow.

The Name parameter has certain restrictions:

The 1st character can only be a letter
The remaining characters can only be letters or numbers.

Connecting Functions
Each function has a number of input and output ports. These define the connection points between functions and determine how
the data will propagate through the FPGA. Certain functions have a variable number of inputs and/or outputs depending on the
actual operation.When a function is initially added to the program, its inputs and outputs are not connected.
Sapera APF shows the current functions in the Design window. The following functions are shown as unconnected.

Note: when clicking on a function in the Design window, the corresponding function will be selected in the
Program window.
The Program panel displays whether a functions input and output links are unconnected, or to which function it is connected. For
example, the following functions input is Unconnected indicating the function output has yet to be defined.

To connect a function output, in the Program Panel, click the required functions Select destination; a drop-down list is opened
which contains all the available target functions in the design to which the current function can be connected to.

Sapera APF Programmer's Manual

Using Sapera APF 28

The Program panel displays the currently connected input and output links, using the function names, appended by the connected
port name (typically In or Out) to indicate its origin/destination.

The Design window is automatically updated with any new function link configurations.

The Design window describes the order of the various operations. The functions may appear in any order in the Program window,
but ultimately it is the order of the connections that determine how the pixels are being processed by the FPGA.

Connection Rules
When creating a connection, the Select destination drop-down list will include all unconnected input ports, even though not
all connections can result in a valid FPGA design. There are a few design rules that must followed:

No input or output can be left unconnected.

The destination functions input must support the data type and format generated by the source functions output.

The resulting connection graph must contain no feedback loop, that is, recursive paths are not directly possible. To
implement such a design, special functions are available; refer to the Recursive Functions section for more details.

The DesignValidate menu command verifies if these connection rules are followed and will display error message to identify
problems that prevent the design from being synthesized to an FPGA firmware.

Sapera APF Programmer's Manual

Using Sapera APF 29

Link Properties
To demonstrate the various function link properties available, load an example program; for example, use the FileOpen menu
command to load the SimpleThreshold example to view a list of functions and their connections:

Several example designs are distributed with Sapera APF; refer to the Sapera APF Introductory Exercises
reference for more details. The .APF design files are located under the \Designs\Examples directory where Sapera
APF was installed.
When two functions are connected, a link is established between the function to allow data to be transferred from the transmitting
function to the receiving function. The link properties describe the format of the data being generated by the transmitting function.
The data format may or may not be accepted by the receiving function, so not all functions can be connected. For example, a
function that generates a color image cannot be connected to the input of a function that only processes monochrome images.
Hints on how to connect function to perform meaningful tasks can be found in the FPGA Designers Guide.
The link properties can be viewed by clicking on the transmitting functions output or the receiving functions input.

Sapera APF Programmer's Manual

Using Sapera APF 30

The list of link properties is as follows:

ColorType

The color type of the pixel data. Possible values are Mono, or one of the supported colors spaces
(RGB, YUV, HIS).

Arithmetic

Indicates if pixels are interpreted as signed values. Possible values are signed or unsigned.

BitWidth

Number of bits per pixel. Can range from 1 to the maximum input bit width supported by the
function.

PixelsPerClock

Number of pixels transferred in parallel. Increasing the number of pixels per clock will increase the
maximum sustainable bandwidth but will also increase the FPGA resource usage.

KernelHeight

Number of kernel rows. Some functions operate not on individual pixels but on local group of
pixels called kernels. Some of these functions are used for filtering images. See the Using Kernels
section for more details.

KernelWidth

Number of kernel columns.

MaxFrameWidth

Maximum frame width, in pixels, that can be transferred by the function. Enough FPGA resources
will be allocated to make sure that images of dimensions equal or less than the maximum
dimensions can be processed. In particular, the maximum frame width can have an influence on the
usage of the FPGAs internal memory.

MaxFrameHeight

Maximum frame height, in pixels, that can be transferred by the function.

DataType

Data type of the input. Possible values are Image, Line, Pixel or Signal. Indicates how or if end-ofline and end-of-frame internal flags are used to synchronize data between functions. Currently, the
Image I/O::CameraIn function generates Image data type and so this data type is typically used
throughout designs, except where Signal I/O functions are used.

For most functions, Sapera APF automatically sets the functions output properties, in which case the properties are read-only
(that is, they cannot be edited). Sapera APF determines the value of each of the link properties based on several factors:

The transmitting functions input: for example, the Boolean::GreaterThanVal function generates images that have the
same dimensions as its input images. In this case, the MaxFrameWidth and MaxFrameHeight values at the output of the
GreaterThanVal function are the same as the values at the input of the function.

The transmitting function itself: some functions change specific properties. For example, the Boolean::GreaterThanVal
function generates output values with 1 bit per pixel, regardless of the bit width of the pixels at its input. This can be
viewed in the BitWidth property of the link at the output of the GreaterThanVal function.

The functions parameters: for example, the Image I/O::CameraIn functions has parameters MaxFrameHeight and
MaxFrameWidth. By setting these values, Sapera APF is given boundaries for the maximum image dimensions that can

Sapera APF Programmer's Manual

Using Sapera APF 31

be processed by the FPGA design. When these values are changed, the same values are updated in the output link
properties.

Note: since most functions do not change the image dimensions, the Image I/O::CameraIns MaxFrameWidth and
MaxFrameHeight parameter values are typically propagated throughout the FPGA design. Since these
dimensions can have a significant effect on the FPGA resource usage, it is advisable to set the maximum image
dimensions for the CameraIn function to the smallest values possible, typically the dimensions of the images
generated by the target camera.
Some functions have output link properties that can be edited. For example, the StreamControl::Serialize function can reduce the
number of pixels per clock. When displaying the properties of the link at the output of the Serialize function, the value of the
PixelsPerClock property is not grayed-out:

Sapera APF Programmer's Manual

Using Sapera APF 32

Creating Function Groups

Function groups are useful to create complex processing designs. Groups can be created by clicking on one of the
Program window.

icons in the

After a group has been created, it can be renamed by double-clicking on the groups name. Functions (or other groups) can be
moved to the group by using the mouse select the function name and then to drag-and-drop it into the group. The Design window
will automatically be updated:

After the functions within a group have been validated, the group can be collapsed in the Program window to hide it from view to
allow focusing on other parts of the algorithm being designed:

Sapera APF Programmer's Manual

Using Sapera APF 33

Validating a Design
When the Sapera APF design is complete, the design must be validated before it can be simulated. Validation is required to make
sure it can correctly be implemented on an FPGA (see the FPGA Design Rules section for more details). Simulating a design
allows the use of test images to validate the image processing algorithm and parameter settings at each function stage.

FPGA design rules do not allow unconnected outputs or inputs. Unused outputs can be terminated by a
StreamControl::Trash function. This allows a design to pass the validation rules and to perform simulation of a
partial design.
Use the Design > Validate menu command to validate a design. The Output Message window displays any error messages or if
the synthesis was successful.

Design Simulation
After the Sapera APF design has been validated, a test image can be loaded and the processing algorithm and parameter settings
verified. The Sapera APF simulation is used to validate the image processing chain and validate the designs image output.
To create the processing simulation, use the Design Simulate menu command.

Each function has a bit-accurate software model equivalent to the FPGA implementation, which allows for fast simulation. The
simulation is performed on a frame-basis (not a pixel basis) and are bit-accurate, hence no waveforms are required. The resulting
frame from every function in the design can be viewed. However, the simulation does not check the temporal behavior of the
FPGA in actual clock cycles, hardware-dependent delays, or simulate signal IOs.
The Simulation tab allows you to select a test image for the Image I/O::CameraIn output. Sample image files are distributed with
Sapera APF and are located under the \Images in the installation directory. Each function output can be displayed by enabling the
associated probe.

Sapera APF displays the selected source image and function outputs in individual windows.

Sapera APF Programmer's Manual

Using Sapera APF 34

Note that by default, the simulation image windows automatically adapts to improve the dynamic range of the displayed pixel
values. For example, an image with 1 bit per pixel will be displayed as a black and white image. Right-clicking on the image will
show a menu that allows to select how many bits are actually displayed. An image with 1 bit per pixel, displayed with the usual 8
bits per pixel, will show up as a black image, because the pixel values are too low to register on the screen:

In any case, the numerical value of the pixel under the mouse cursor is always displayed at the bottom-right of the Sapera APF
window:

Sapera APF Programmer's Manual

Using Sapera APF 35

Placing and Routing a Design

When the Sapera APF design is satisfactory, the design can be mapped to the FPGA by the Xilinx ISE tools. This is started by
using the Design Place & Route menu command.
The Output Messages window provides details on the progress of the placing and routing of the design:

The placing and routing procedure can be quite lengthy, even for relatively simple designs, depending on the host hardware CPU
capabilities. If necessary, the operation can be aborted using the Design Abort Place & Route menu command.

When completed, a message is displayed indicating that the firmware generation was successful. The resulting cbf, cbg, and xml
files will be placed in an output directory listed in the Output Messages window.

Alternatively, if the Xilinx ISE tools failed to generate a design which respects all FPGA timing constraints, it will display a
different message:

In this case, the resulting cbf, cbg, and xml files are still generated and copied into the output directory, but they may or may not
function correctly when loaded into the frame grabber. If needed, the Xilinx ISE random seed setting can be modified, then
Design Place & Route started again. Refer to the Application Settings section for more details.

Sapera APF Programmer's Manual

Using Sapera APF 36

Resource Utilization
Before beginning the Place and Route operation, it is recommended to verify that sufficient resources are available for the design.
The FPGA resource calculation for the design is performed using the menu command Design Resource Estimation.

The results of the estimation are then available in the Resouce window. The values displayed are shown as a percentage of the
total FPGA resources specifically available for processing.

As long as FPGA resources are available, additional processing functions can be added with little or no increase in processing
time.
Note that the resource utilization is only an estimation; the actual values can only be obtained by doing the place and route of a
design. This information will be available in the Output Messages window; after the place and route has been completed; it will
be located near the bottom of the Xilinx tools text output and will be similar to the output below:
(Info)
(Info)

Slice Logic Utilization:

Number of Slice Registers:

(Info)

Number used as Flip Flops:

(Info)

Number used as Latches:

(Info)

Number used as Latch-thrus:

(Info)
(Info)

Number of Slice LUTs:

Number used as logic:

22,495 out of

69,120

32%

19,332 out of

69,120

27%

17,203 out of

69,120

24%

17,920

10%

17,280

62%

22,487
7
1

(Info)

Number using O6 output only:

15,003

(Info)

Number using O5 output only:

1,156

(Info)

Number using O5 and O6:

1,044

(Info)
(Info)

Number used as Memory:

Number used as Dual Port RAM:

1,951 out of
949

(Info)

Number using O6 output only:

292

(Info)

Number using O5 output only:

108

(Info)

Number using O5 and O6:

549

(Info)

Number used as Single Port RAM:

(Info)

Number using O6 output only:

(Info)

Number used as Shift Register:

997

(Info)

Number using O6 output only:

997

(Info)

Number used as exclusive route-thru:

(Info)

Number of route-thrus:

178
1,433

(Info)

Number using O6 output only:

1,314

(Info)

Number using O5 output only:

101

(Info)

Number using O5 and O6:

18

(Info)
(Info)

Slice Logic Distribution:

(Info)

Number of occupied Slices:

10,760 out of

(Info)

Number of LUT Flip Flop pairs used:

28,719

(Info)

Number with an unused Flip Flop:

6,224 out of

28,719

21%

(Info)

Number with an unused LUT:

9,387 out of

28,719

32%

(Info)

Number of fully used LUT-FF pairs:

13,108 out of

28,719

45%

(Info)

Number of unique control sets:

(Info)

Number of slice register sites lost

69,120

8%

(Info)

to control set restrictions:

2,576

5,742 out of

(Info)
(Info)

Specific Feature Utilization:

Sapera APF Programmer's Manual

Using Sapera APF 37

(Info)

Number of BlockRAM/FIFO:

51 out of

(Info)

Number using BlockRAM only:

34

(Info)

Number using FIFO only:

16

(Info)

Number using BlockRAM and FIFO:

(Info)

Total primitives used:

Number of 36k BlockRAM used:

(Info)

Number of 18k BlockRAM used:

11

(Info)

Number of 36k FIFO used:

11

Number of 18k FIFO used:

(Info)

Total Memory used (KB):

34%

5,328

31%

(Info)

(Info)

148

27

6
1,674 out of

The items of interest in this list are:

Number of occupied slices: this generally indicates how many resources are taken for processing. If the value is too
high, the Xilinx tools will not be able to complete the designs place and route. In this case it may be required to reduce
the complexity of the processing or to reduce the value of PixelsPerClock.

Number of BlockRAM/FIFO: this indicates how many of the FPGAs internal memory are used. If the value is too
high, it can be reduced by decreasing the MaxFrameWidth parameters of various links, or the height of kernels at the
output of KernelCreate functions.

Saving
Use the File Save or File Save As menu command to save the Sapera APF design. Sapera APFs designs are saved as files
with an .apf extension.
Note, user designs must not be saved in the Teledyne DALSA\Sapera
APF\Designs\Examples folder as this folder is reserved for Sapera APF .examples.
Writing user files to this directory can result in the design not being correctly saved.
If necessary, the design file can be password protected. To set the password for the design file, use the File Set Design
Password menu command. The password is then required to open the file.

Sapera APF Programmer's Manual

Using Sapera APF 38

Application Settings
Several applications settings are available through the OptionsEdit menu.

The main settings of interest include:

Save output messages to file:
When this option is enabled, all entries displayed in the Output Messages window will also be sent to file
SaperaAPF_LogFile.txt located in the \bin directory where the SaperaAPF.exe program resides.
Xilinx ISE options
This setting is used to support various versions of the Xilinx ISE tools. The default value is 10.1 in order to be
compatible with the older versions of Xilinx ISE, but when selecting 13.x this will enable optimization features only
available with the more recent versions of Xilinx ISE. This setting must be set prior to the place and route.
Xilinx ISE random seed
This setting can be modified when the Xilinx ISE tools were not able to generate a firmware which respects all FPGA
timings constraints. The resulting firmware may or may not function correctly. If needed, the Xilinx ISE random seed
setting can be changed. This will instruct the Xilinx ISE tool the next time they are used through the Design Place &
Route menu command to start with a different initial random placement. Changing this initial placement can allow the
Place & Route tools to reach better timings. This is a trial-and-error process; there is no way to determine which ISE
random seed will help route a given design. In the worst case scenario, several iterations of Place & Route may be
required.

Sapera APF Programmer's Manual

Using Sapera APF 39

Testing the Firmware using the RTPro Demo

To test the Sapera APF design using the RTPro Demo, the Sapera APF design firmware generated by the Place and Route
operation must be loaded onto the Teledyne DALSA frame grabber.

Loading Sapera APF Firmware

To load the design firmware:
1.

Launch the Device Manager utility provided with the Teledyne DALSA frame grabber driver.

2.

Click the Device Info tab, click Firmware > ACU/DTE + PCIe x4 Interface in the Device tab, and click Browse in
the File Name field to select the required Sapera APF firmware .cbf file.

3.

Click Program to initiate transfer of the firmware to the boards flash memory. This firmware will be loaded into the
FPGA when the board is reset. Next, click Reset to activate the new firmware.
For users wanting to prevent their firmware from being loaded onto unauthorized frame
grabbers, a special custom signature function is available upon request. This function
embeds a user-specific signature into the firmware. When such a signature is found, the
firmware can only be loaded onto a board that has been authorized by the user with the
same signature. For more information please contact a Teledyne DALSAs sales
representative.

The .xml and .cbg files generated alongside the .cbf file should be kept in the same
directory. If the files are moved, if their directory is renamed or if the VX4 frame grabber
is moved to a different computer, the Device Manager should be run again to reload the
.cbf file in the right directory.

Sapera APF Programmer's Manual

Using Sapera APF 40

Using the VX4 RTPro Demo

The RTPro Demo is distributed with Sapera APF and allows for evaluation of any firmware without requiring prior software
integration of the firmware. It will query the firmwares list of parameters through Sapera LTs SapAcqDevice object, and present
this list of parameters to the user through a graphical interface.
The VX4 RTPro Demo is available for both 32-bit and 64-bit platforms and is available from the Windows Start Menu shortcut
All Programs > Teledyne DALSA > Sapera APF.
The application allows you to control the acquisition using Snap, Grab, Freeze, and Abort buttons. If the firmware design contains
processing parameters their values can be adjusting using their individual fields available in the Processing Parameters panel.
If multiple outputs are available, the required output to view can be selected in the Display section.

The applications GUI contains several sections:

Acquisition
The buttons in this section allow control of the frame grabbers front-end interface to the camera, to start acquisition of a single
frame (Snap), to start continuous acquisition (Grab) or to stop ongoing transfers (Freeze or Abort).

Processing Parameters
This section lists all the parameters available for the currently loaded design. Some of these parameters are related to the FPGA
designs functions, while other parameters describe the available outputs (dimensions, format, name, and so forth).
Read-only parameters, which cannot be modified, are grayed-out. Also, by default, the list only contains the parameters that have
been identified as Beginner parameters. By changing the value of the Parameter Visibility list box, more advanced parameters
can be displayed. These advanced parameters allow more freedom in the configuration of the firmware, such as manually
overriding the automatically computed buffer dimensions allocated in the host memory to receive images.
WARNING: Depending on the loaded firmware, changing buffer dimensions may cause unrecoverable system
errors, which require a system restart; therefore, exercise caution when changing these values.

Sapera APF Programmer's Manual

Using Sapera APF 41

Enabled transfers
This section lists all the outputs available in the FPGA design, that is, all the Image I/O::FrameOut functions used in the design to
output images to the host computers memory.

For each selected output, the RTPro Demo queries the FPGA firmwares parameters to determine the dimensions and format of
the buffer it should allocate for this output, and connects the FPGAs output to these buffers. When images are acquired by the
front-end, they are fed to the FPGAs processing section as designed in Sapera APF. The processing section processes each
incoming image and eventually sends the resulting image to the hosts memory, triggering a callback function in the host
application to indicate that a new image is ready.
Buffer and Display
The list box in the Display section contains one entry for each enabled FPGA output.

The Buffer section contains the configuration of the buffer at the selected output. It is this buffers contents that get displayed in
the image display.

Status
The frame grabber implements the Trigger-to-Image Reliability framework which insures that no frames from the camera can
ever get dropped without the host application being notified. The host application (in this case, the RTPro Demo) can register to
receive callbacks at certain events, and the count of those events is displayed in the Status section.

Events displayed are:

Frame grabbed: an image was received from the camera
Frame lost: an image was dropped due to insufficient downstream bandwidth, either in the processing section or in the
PCIe bus.
Frame overflow: an image was dropped due to insufficient bandwidth in the Camera Link front-end.
Frame received: the host application received an image. There are separate events for each enabled output.
Frame trashed: the host application received an image but was unable to process it because it was too slow processing the
previous images.
Board reset
Clicking the Reset button performs a complete hardware reset of the frame grabbers FPGA, which takes a few seconds to
complete. All parameters revert to their initial value following the reset.

Sapera APF Programmer's Manual

Using Sapera APF 42

Key Concepts
The FPGA is loaded with a specific front end that addresses a given camera tap configuration. The front end implements
several features common to all Teledyne DALSA frame grabbers, and as such can be configured through the usual methods; using
the Sapera LT API and .CCF camera files generated using CamExpert.
Features include:
Camera control: this includes driving the CC1 through CC4 lines to the Camera Link camera to determine frame rate,
exposure times, and so forth.
Tap re-ordering and pixel packing
Buffering: images are stored to external memory before they are sent to the processing section. There are flow control
protocols in the FPGA that make sure that all images are processed without losing pixels. If the PCIe bus is temporarily busy,
or if some frames take more time to process than others, then flow control protocols will temporarily pause the upstream flow
of data. When this happens, the incoming frames from the camera are stored to external memory, and one of two outcomes
will happen:
o If processing is paused for a brief period of time, and processing is faster than the cameras bandwidth, then the
processing will catch up and process the frames that were stored to external memory.
o If processing is paused for a long time, or processing is slower than the cameras bandwidth, then the images will
accumulate in external memory up to a point where the memory will be full. When that happens, the front-end will drop
frames and send a message to the host application to indicate that the FPGA designs maximum speed is not sufficient to
sustain the cameras bandwidth.
Cropping: When only part of the image needs to be processed, it can be cropped before it is sent to processing.

Tap reordering and pixel packing

Under the Camera Link protocol, cameras may transfer multiple pixels at the same time to increase the total bandwidth; this type
of camera is considerered to have multiple taps. The position of a given taps pixels in the image depends on that cameras tap
configuration. Two typical tap configurations are interleaved and segmented taps:
2 interleaved taps (tap A + tap B):

2 segmented taps (tap A + tap B):

To simplify the image processing, the front-end reorders the taps to make sure that the images sent to processing are always in
raster-scan order (similar to a 1-tap camera):

Sapera APF Programmer's Manual

Key Concepts 43

Teledyne DALSA frame grabbers usually have a front-end that can support all tap configurations but this consumes FPGA
resources. To free up FPGA resources for image processing, a different approach was taken for firmware generated by Sapera
APF; when starting a design, the user must select a front-end that targets a specific tap configuration, rather than use resources to
support all camera tap configurations. Note that the front-end can later be changed if the target camera changes.
The output of the front end is streamed to the input of the user-defined image processing application on a pixel by pixel basis.
Images are not transferred in frames, but as a stream of single pixels as if in a raster scan , regardless of the cameras tap
configuration. In a raster scan, pixels begin with the first, top left, image pixel (x = 0, y = 0) to the last bottom right pixel, (x =
image width -1, y = image height -1).

One characteristic of FPGAs is that their operating frequency is typically lower than a CPUs frequency, but they can compensate
for lower clock speed by processing data in parallel. Instead of processing a single pixel per clock period, the FPGA can process
multiple pixels. CPUs can do the same using SIMD instructions (for example, MMX, SSE, and so forth) but those instructions are
fixed; if the available instructions are not appropriate to perform a certain operation then multiple CPU instructions must be
combined to reach the final result which reduces the performance of the CPU. On the other hand, the FPGAs configurability and
parallel architecture allows it to apply nearly any operation in real-time. However, the data must first be packed so that multiple
pixels are sent in parallel to the processing functions. This packing is performed by the front-end.
The output of the FPGA front end is always packaged in a 64-bit stream. Depending on the pixel depth of the camera, the link
formatting can be:

Grayscale 8-bits, 8 pixels per clock

Grayscale 16-bits, 4 pixels per clock (for 9-16 bit pixels). The pixels are LSB (least significant bit) aligned.

Sapera APF Programmer's Manual

Key Concepts 44

RGB 24-bits, 2 pixels per clock. The R, G, and B components are respectively LSB aligned, that is, R = {7..0}, G =
{15..8}, B = {23..16}

Sapera APF uses the Image I/O::CameraIn function, which accepts the input pixels from the FPGA front end to initiate the
processing stream. The Image I/O::CameraIn function has a parameter that determines how the front-end will pack the pixels
(please refer to the Image I/O::CameraIn reference description for more details). The simplest design would use the Image
I/O::FrameOutRaw to complete the image transfer to the FPGA back end, which handles the image transfer to the PCIe bus on the
host computer:

Seen in a global context of a frame grabber, the pass-through design can be represented as follows:

The CameraIn function provides a bridge between the FPGAs front-end and the processing section, while the FrameOutRaw
function provides a bridge between the processing section and the FPGAs back-end.

Sapera APF Programmer's Manual

Key Concepts 45

Flow control
The FPGA must manage the input data flow given that the camera is outputting data non-stop, while the PCIe bus may not be able
to transmit data for short periods of time (PCIe latency).
To address this issue, there are flow control mechanisms implemented by Sapera APF on the FPGA. When function As output is
connected to function Bs input, pixels flow from function A to function B, but function B also sends a ready to receive pixels
signal back to function A.
The following diagrams illustrate how the flow control signals are propagated in the FPGA design from the output(s) back to the
input:
1- Starting condition: PCIe is available to receive data. Both CameraIn and FrameOutRaw functions are active:

2- The frame grabbers back-end detects that the PCIe is not available to transmit data.

3- In turn, the FrameOutRaw function indicates that it is not ready to receive data:

Sapera APF Programmer's Manual

Key Concepts 46

4- In turn, the CameraIn function notifies the front-end that the processing section is not ready to receive data:

To prevent losing the incoming images from the camera, they are buffered by the front-end to external memory until the
CameraIn function is ready to receive data again, which happens when the PCIe bus becomes available again. The images will
accumulate in external memory, but if at some point the external memory becomes completely full, the front-end will drop
incoming images from the camera. If that happens, the frame grabber will notify the host application with a
SapAcquisition::EventFrameLost message to indicate that a frame (or image) was lost.

Multiple outputs (non-merged parallel branches)

Up to four FrameOut functions can be used; FrameOutRaw, FrameOut2, FrameOut3, and FrameOut4. Multiple outputs can be
used when different processing operations are required on the same input image. The Multiple Outputs example design
demonstrates this concept; to load the design use the FileOpen menu command.

The first thing to notice is the use of the StreamControl::BranchCreate function to duplicate a stream of pixels into multiple
branches. This illustrates differences between FPGAs and CPUs:

On a CPU, in order to implement different processing paths using the same source image, multiple functions have to be
called consecutively. Since the image is in memory, it can be used as the source of each of the consecutive function calls.
On a multi-core CPU, if you have more threads running at full speed than you have CPU cores, the threads will slow
down.

On an FPGA, all processing branches run simultaneously in parallel. As the pixels arrive, they are not stored to external
memory (as on a CPU) but instead are directly fed to the FPGA circuits that implement the various processing functions.
On the FPGA, multiple branches can run at full speed in parallel (but FPGA resource usage will increase accordingly).

The BranchCreate function is used to duplicate an input pixel stream into multiple branches that will then be executed
simultaneously and independently. Those branches can either be merged together for further computations on the FPGA (see the
reference section for more details), or sent directly to the host CPU. In the MultipleOutput example, at the end of each sequence
there is a FrameOut function which sends results to the frame grabbers back-end and out to the host CPU.
Note: the StreamControl::BranchCreate function can have more than 2 outputs. The BranchCreate functions output
node has a property named Number of BranchCreate output port(s). When changing this value, either outputs will be
added, or existing outputs will be removed (and disconnected if they were connected).

Sapera APF Programmer's Manual

Key Concepts 47

The FrameOut functions have the following attributes:

Only one copy of each FrameOut function can be inserted in a design. For example, it is not possible to have two
FrameOutRaw functions, or two FrameOut2 functions.

When an FPGA firmware is generated, its XML description file lists all the outputs available for this firmware. The userspecified name given to a FrameOut function output is used by the XML file. The host application can use the Sapera LT
API to parse this XML description file and get information about the outputs such as the number of outputs, each
outputs format and dimensions, and so forth. Refer to the Using Sapera APF Firmware section for more details.

If an output is available, it is mapped to an output port that can be accessed through the Sapera LT API. The host
application can use this API to allocate buffers and create transfers to receive the data generated at these output ports.

The FrameOutRaw function is special within the Sapera LT API since it is mapped to the default output port of the
SapAcquisition object. This means that when a FrameOutRaw function is present in a firmware, it can be used by any of
the standard Sapera LT applications, that is, CamExpert, Grab Demo, Sequential Grab Demo, and so forth. However, the
FrameOutRaw is restricted to always output images with the same dimensions and format as the input received from the
CameraIn function.

Each output can be enabled independently. This is done automatically by the frame grabbers driver; whenever an
output port has been connected to a buffer, it is enabled in the FPGA.

The FrameOut function expect images that have a fixed width. If images are generated with variable width, the
StreamControl::RectangleReshape function can allow these images to be used as input to Image I/O::FrameOut
functions.

Sapera APF Programmer's Manual

Key Concepts 48

Estimating a designs data throughput

The maximum bandwidth that a given FPGA design can sustain can be estimated by inspecting the various links in the design.

Example for a single branch

In the PassThrough example, the design contains a single link, between the Image I/O::CameraIn function and the FrameOutRaw
function:

The properties that have a direct influence on this links bandwidth are the links BitWidth and its PixelsPerClock. The basic rule
to compute the maximum bandwidth this link can sustain is:
((BitWidth/8) * (PixelsPerClock) * (FPGA base frequency) ) bytes per second
This formula derives from the fact that for each clock cycle, the FPGA processes multiple pixels in parallel.

On the Xcelera-VX4, as of release 1.0 of Sapera APF, the base FPGA frequencies are as follows:
Front-end
80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

Base FPGA design frequency

All other front-ends

100 MHz

112.5 MHz

In the PassThrough example, assuming that the FPGA is running at 100 MHz, the maximum sustainable bandwidth in the
designs single link is:
8 bits per pixel * 1 byte per pixel * 8 pixels per clock cycle * 100M clocks cycles per second
= 800 MB/s.
If a given branch contains multiple functions, the maximum sustainable bandwidth is determined by the branchs bottleneck. If a
given branch contains links different bandwidths the lowest bandwidth defines the limit; for example, given a branch having a
link with a maximum of 800 MB/s and another link with maximum of 400 MB/s, the branchs maximum bandwidth will be 400
MB/s. When such a bottleneck exists, FPGA resources are wasted on the high bandwidth links and connected functions, because
FPGA resources are allocated to transmit and process this high bandwidth even though it can never be reached, therefore it is
advantageous from a design perspective to lower the parallelism of the higher links to the same throughput as the slowest link.
Refer to the data parallelism section for information on how to optimize parallel designs.

Sapera APF Programmer's Manual

Key Concepts 49

Example for parallel branches branches with identical maximum bandwidth

In the MultipleOutputs example, the PCIe bandwidth is too low to sustain the designs output because it has multiple outputs.
Each output DMA (Direct Memory Access) channel on the frame grabber is independently enabled and the PCIe bandwidth is
shared among enabled DMAs. If the total bandwidth temporarily exceeds the PCIe bandwidth, flow control is automatically
activated and pauses upstream functions to ensure no pixels are lost; the camera front-end performs buffering to external memory.
If external memory overflows, the host application will receive a bandwidth overflow message.
The maximum bandwidth at the Image I/O::CameraIn output will then depend on the number of outputs. Assuming that the
PCIes maximum bandwidth is 800 MB/s, then if all four outputs are enabled the maximum camera bandwidth is 800 MB/s / 4 =
200 MB/s.

Example for parallel branches branches with different maximum bandwidths

When a StreamControl::BranchCreate function is used to create parallel branches, the maximum bandwidth at the input of the
BranchCreate function is equal to the lowest bandwidth of all the branches.
For example, we can analyze a design where a BranchCreate function is used to create two parallel branches.

In the left-most branch, a StreamControl::Serialize function is used to reduce the number of pixels per clock to 1. The maximum
bandwidth at the output of the Serialize function becomes:
8 bits per pixel * 1 byte per pixel * 1 pixels per clock cycle * 100M clocks cycles per second
= 100 MB/s.
Consider the branch formed by the following functions:
CameraInBranchCreateSerializeBitwiseNotFrameOut4
Even though the links from CameraIn to Serialize can sustain up to 800 MB/s, that bandwidth drops to 100 MB/s at the output of
the Serialize function. Because of the flow control mechanism, this 100 MB/s maximum bandwidth propagates up to the
BranchCreates input; the maximum bandwidth for the right-most branch is then reduced from 800 MB/s to 100 MB/s:

Sapera APF Programmer's Manual

Key Concepts 50

Parallelism
On the FPGA, parallelism can be organized into three functional categories:
1.
2.
3.

Branch parallelism (covered in the Multiple outputs and Merged parallel branches sections)
Link parallelism (bit-level and pixel-level)
Function parallelism

Link parallelism
Every link between two functions has a parallelism, which specifies the number of pixels input to the function at one time. The
level of parallelism is set by the Pixels per clock property.
As such, parallelism can be used to increase the bandwidth of a given link. If only a single pixel is transferred, the link has a
parallelism of 1. The format of the pixel determines the bit width of the link. For example, an 8-bit pixel has a bit width of 8 and
presents the destination functions input 8 signals, each representing a single bit (0 or 1). In simplified terms, this link can be
considered as a data bus where 8 bits are being sent in parallel:
8-bit
Pixel

Bit width = 8

To function

With parallelism, more than one pixel can be presented to the function at one time. A parallelism higher than one results in the
simultaneous transfer of multiple pixels between functions. For example, a parallelism of 8 transfers 8 pixels to the destination
function at the same time, using 1 clock cycle, for a total throughput of 64 bits (for pixels with an 8-bit width):
Parallelism = 8 pixels
0

Throughput = 64 bits

To function

Sapera APF Programmer's Manual

Key Concepts 51

Function parallelism
Functions must be able to process all the pixels at their inputs in real-time. If a given function receives 8 pixels per clock, it must
contain 8 computation engines to process these pixels in parallel. This parallelism directly influences the number of resources to
implement the function. This affects FPGA memory and logic resources. In general, a doubled parallelism double s the required
resources.
Thus, when considering the image processing design, parallelism can be a factor in determing what is possible given the available
resources; parallelism may have to be reduced to allow for more operations, or less operations can be performed at a higher
parallism.
Not all functions can handle every size of bit width and their input may be limited to certain specific bit widths, or ranges of bit
widths. Refer to the Sapera APF Reference section for detailed descriptions of each function, including their accepted bit widths
and parallelism (pixels per clock). Some functions only accept certain bit widths and parallelism because of their implementation.
Other functions will accept only certain formats because of physical restrictions:

Image::FrameOut functions: on the Teledyne DALSA VX4 frame grabber, these functions pack the data into 64-bit
chunks. Therefore it can receive either 8 pixels at 8-bits per pixel, 4 pixels are 16-bits per pixel or 2 RGB32 pixels.
FrameBuffer functions: in order to match the physical data bus to external memory, the FrameBuffer transfer is optimal
when it receives 128-bits of data per clock (for DDR) or 32-bits of data per clock (for RLDRAM).

When such restrictions are found in a design, two functions can be used to change the parallelism:

StreamControl::Serialize: This function reduces the parallelism. For example, if a link is at 8 pixels per clock but the
target destination function only accepts 4 pixels per clock, the Serialize function can be used to reduce the pixels per
clock from 8 to 4. When the function receives 8 pixels in a given clock cycle, it pauses its input; then outputs the 1st 4
pixels, then the remaining 4 pixels. It then restarts its input to receive the next 8 pixels. This has the effect of reducing
the maximum bandwidth on the input link. This function is also discussed in the Example for parallel branches
branches with different maximum bandwidths section.

StreamControl::Parallelize: this function increases the number of pixels per clock. For example, if a function generates 4
8-bit grayscale pixels at every clock cycle, it cannot be output directly to the host CPU through an Image::FrameOut
function, since the FrameOut function requires the image to be in gray8x8 format (8 8-bit grayscale pixels). Therefore,
the parallelism must be increased using a Parallelize function, which will accumulate 2 consecutive chunks of 4 pixels to
output a single 8-pixel chunk to meet the format requirements of the FrameOut function.

In general, whenever a bottleneck is found in a given link, it is advisable to use the Serialize function as early as possible in the
sequence to reduce the pixels per clock to the same bandwidth as found at the bottleneck. This ensures that only the minimum
required resources are allocated on the FPGA.

Sapera APF Programmer's Manual

Key Concepts 52

Merged parallel branches

The creation of parallel branches using the StreamControl::BranchCreate function has already been introduced in the Multiple
outputs (non-merged parallel branches) section, which describes separate parallel branches directly output to the host CPU not
merged back together in the FPGA. Typically though, the output of parallel branches needs to be merged through an operation for
further processing on the FPGA. The FlatLineCorrection example (shown here in a version modified for display) demonstrates
this concept:

In the flat-line correction algorithm, a value is subtracted from every pixel to compensate for the camera sensors dark leakage
current, that is, the pixels value when no light hits the camera sensor. This value depends on the pixels horizontal coordinate. To
calculate the appropriate value to substract from the original value of each pixel, the PixelControl::XPos function extracts the
pixels horizontal coordinate to use as an index of a look-up table. This LUT determines which value must be subtracted for each
pixel (assuming that the contents of this look-up table have been calibrated by the host application for the camera being used).
By analyzing how the data arrives at the input ports of the Subtract function, it can be correctly assumed that the pixels going
through the XPos and ApplyLUT functions take longer (in number of FPGA clock cycles) to arrive at the Subtract function than
the pixels arriving directly from the BranchCreate. The net effect of having the XPos and ApplyLUT delaying the pixels (with
regards to the unprocessed pixels) is equivalent to introducing a horizontal shift in the image.
Due to this timing delay between branches, if on a given clock cycle the Subtract function performs the subtraction of the pixels
present at its input ports, the wrong behavior results the Subtract function would be subtracting pixels that do not have the same
pixel position in the image. The approach taken by Sapera APFs FPGA synthesis engine is to introduce a delay in the Subtract
functions input that is connected directly to the BranchCreate function. By making this delay equal to the delay seen on the other
branch, the Subtract function always sees pixels at its input which have the same position in the image. This assumes that we can
compute the delay introduced by the XPos and ApplyLUT functions, which introduces the concept of fixed-latency functions vs.
variable-latency functions.

Fixed-latency functions vs variable-latency functions

A functions latency is the delay (in number of FPGA clock cycles) between the moment where data is available at a functions
input, and the moment where the corresponding result are placed at the functions output. Function latency can be divided into
two main types: Fixed or Variable.
The Properties page for each function contains a read-only field LatencyType that displays whether the function is Fixed or
Variable:

Fixed latency: Functions that always use the same amount of time to process input pixels, independent of the pixel values. For
example, arithmetic functions, color conversion, and look-up tables (LUTs) all have fixed latency.
Variable latency: Variable latency functions are typically more complex than fixed latency functions. Their latency cannot be
determined in advance, either because the time it takes to compute results depends on the input values, or they are linked to
external components. Also, functions that modify the number of pixels are variable latency functions.

Sapera APF Programmer's Manual

Key Concepts 53

Synchronization of parallel branches

When parallel branches are merged together, it is important that the branches are correctly synchronized. This depends on the
latency type of the functions on each branch.

If there is no variable-latency function present on any of the merged branches, synchronization is taken care of by Sapera
APFs FPGA synthesis engine. Fixed-latency functions can be connected in any order, as is done in the FlatLineCorrection
example:

When at least one of the branches contains a variable-latency function, then the StreamControl::BranchSync function must be
used to perform synchronization. If a branchs pixels arrive at the BranchSync function sooner than other branches, the
BranchSync performs flow control and temporarily pauses this fast branch to let the other branch(es) catch up, as is done in
the Sync Memory Banks example, which contains Memory::FrameBuffer functions that have a variable latency:

When pixels are available on all branches of the StreamControl::BranchSync function, they are read and output simultaneously at
the output of the function; the synchronized parallel branches can then be merged by being connected to the inputs of the same
function.
Sapera APF Programmer's Manual

Key Concepts 54

This synchronization method assumes that the branch paused by BranchSync is able to buffer pixels the when it is paused. If it
cannot buffer pixels, the FPGA design may encounter a deadlock situation, as illustrated in the following design:

The Kernel::KernelCreatefunction has a variable latency it introduces a delay that depends on the height of the kernel being
created. The Kern3x3 introduces a delay of 1 line, while the Kern5x5 introduces a delay of 2 lines (this delay is needed to acquire
the necessary lines to complete the kernel around the target pixel). This means that the branch with the Kern3x3 function will start
generating output data a whole line sooner than the branch with the Kern5x5 function.
Note: the kernel functions are covered in more details in the Using kernels section.
In this design, pixels are sent to both branches. After the 1st line has been processed by the Kern3x3 function, it starts outputting
pixels which reach the BranchSync function. The BranchSync function will pause this branch, and the flow control will propagate
up to the CameraIn function:

At this point, the FPGA has reached a deadlock situation:

- BranchSync stops the right-hand branch until the left-hand branch generates data;
- Pausing the right-hand branch results in a stop of both branchess source;
Sapera APF Programmer's Manual

Key Concepts 55

Stopping the left-hand branchs source results in the left-hand branch never being able to generate data.

When this situation occurs, the FPGA will stop outputting data. To solve this problem buffering must be added on the fast branch,
as is done in the Sync Variable Latency example:

By using a Memory::LineBuffer function, the flow control on the faster right-hand branch does not propagate back up to the
CameraIn function. Instead, the LineBuffer accumulates pixels, and as the slower left-hand branch starts generating data the
BranchSync allows both pixel streams to flow through.
Since the FPGA synthesis engine does not have the capability of analyzing the amplitude of the variable latency, it is the
designers responsability to provide buffering using using a Memory::LineBuffer or a Memory::FrameBuffer function.
Note that when validating a design that contains a StreamControl::BranchSync operator with variable latency operator, the
following warning message will be displayed even if buffering was correctly provided; in this case the warning message can be
ignored:

Sapera APF Programmer's Manual

Key Concepts 56

Using Kernels
Several image processing functions process each pixel individually, for example, the Math::ApplyLUT or
Boolean::GreaterThanVal functions. For these functions, a single input pixel is sufficient to generate an output result. Other
functions need to read not only the current input pixel, but also the surrounding input pixels. Such image filtering functions
include smoothing, sharpening, removing noise and edge detection. In Sapera APF, this neighborhood of pixels surrounding the
current input pixel is called a kernel.

Kernels are created using the Kernel::KernelCreate function. For each input pixel, the KernelCreate function outputs a small
matrix of pixels centered on this input pixel. Typically, this matrix will be no larger than 7x7. After a kernel has been created, it
can be processed by one of the other functions in the Kernel library, as shown in the Gaussian5x5 example design:

The dimensions of the kernel can be set by changing the KernelHeight and KernelWidth properties of the link at the output of the
KernelCreate function. In the Gaussian5x5 example, at every FPGA clock cycle the KernelCreate function outputs 8 kernels of
5x5 pixels each, for a total of 200 pixels:

The concept of kernel differs depending on whether a filtering function is being implemented on a CPU or on a FPGA:
On the CPU (for example, using Sapera Processing), the word kernel specifically refers to the coefficients of a convolution
matrix. This implementation can be visualized as sliding the convolution matrix over an imagethat remains in place in
memory.

On the FPGA, the kernel refers to the moving neighborhood extracted from the image as it is being received. This
implementation can be visualized as the convolution coefficients remaining in place in the FPGA hardware and the image
moving into the FPGA. The net effect of the FPGA implementation is the same as for the CPU implementation, but the
difference in implementations explains why the word kernel on the FPGA refers to the input image pixels, whereas on the
CPU it refers to the operation being applied.

Sapera APF Programmer's Manual

Key Concepts 57

FPGA Resource Usage Considerations When Using Kernels

Kernels and FPGA LUTs and registers
In the Gaussian5x5 example, at every FPGA clock cycle the Kernel::KernelCreate function outputs 8 kernels of 5x5 pixels each,
for a total of 200 pixels. To be able to process these 200 pixels at every FPGA clock cycle, the Kernel::Convolution function that
receives those pixels must allocate enough FPGA resources to perform 200 multiplications in parallel, which consumes a large
amount of the FPGAs available LUTs and registers elements. There are 2 methods to reduce this FPGA resource usage:
1.

Reduce the kernel dimensions: always keep the kernel dimensions to a minimum. In the Gaussian5x5 example, reducing
the dimensions of the kernel to 3x3 instead of 5x5 will reduce the number of parallel FPGA multiplications from 200 to
8x3x3 = 72.

2.

Reduce the number of pixels per clock, as is demonstrated in the Median Filter example. By using the
StreamControl::Serialize function to reduce the number of pixels per clock from 8 to 4, the total number of simultaneous
pixels at the output of the KernelCreate function is reduced from 200 to 4x5x5 = 100. By reducing the number of pixels
per clock we reduce the designs maximum sustainable bandwidth, but this can be acceptable depending on the input
cameras bandwidth.

Kernels and FPGA Block RAM

When creating kernels in Sapera APF consideration must be given to the FPGA resources required to to create a kernel of a
specific size.
Since creating a kernel requires reading input pixels across multiple rows and columns, these pixels must be buffered in the
FPGAs internal memory (block RAMs) from the image stream. For example, to create a 3x3 kernel, 3 lines of an image are
required:

To reduce the usage of the FPGAs block RAM, two design methods are available:
1.

Reduce the kernel height. This reduces the required number of line buffers. Note that changing the kernel width has little
effect on the usage of the FPGAs block RAM.

2.

Reduce the maximum line width. Each line buffer must be allocated large enough to hold all the pixels of the incoming
images. Since the block RAM are statically allocated, the line buffers must provide for the worst case, that is, the lines
maximum width, which can be modified by changing the MaxFrameWidth parameter of the Image I/O::CameraIn
function.

Computing Convolutions
The Kernel::Convolution function is one of the most often used image processing operations and is demonstrated in the
Gaussian5x5 example.
Convolution output bit width
The BitWidth and the Arithmetic (signed or unsigned) of the values at the output of the Convolution function are automatically
determined by Sapera APF. The output bit width accommodates the largest possible value that can be generated by the
convolution, depending on the input pixels bit width and the convolution coefficient values. An extra output sign bit is also
added if at least one of the coefficients is negative.

Sapera APF Programmer's Manual

Key Concepts 58

Normalizing the output

Depending on the requirements of the application, the convolution result values can be normalized by dividing them by a scaling
value. This returns the values to the same bit width as the input image. The scaling value is calculated by summing the
convolution coeffiecients. For example, the scaling value for the following 3x3 convolution coefficients is 45
(1+2+3+4+5+6+7+8+9 = 45):
1

Another common example is a 3x3 kernel holding all 1's (with a scaling value of 9) which performs a low-pass filtering
(smoothing) operation. Each pixel in the new image is the average of its 8 neighbors and its original value.
To perform division on the FPGA, the Math::Divide functions can be used, though it is resource intensive. To reduce resource
usage, an alternative method using the Math::MultiplyByVal and Math::ShiftRight functions can approximate the division
operation.
The Math::ShiftRight functions as a division by factors of 2, depending on the number of bits that are shifted. The value of the
shift right is chosen depending on the divisor; if it is too small the division approximation may be too rough and not accurate
enough. The multiplication factor is rounded to an integer value.
For example, to approximate a division by 273, a shift right of 12 provides an accurate enough approximation, resulting in a
multiplication factor rounded to 15:
(1/273)*(212) = 15.003663
The approximation of 1/273 thus becomes 15/4096, and is easier to implement in the FPGA:

1
273

15
4096

Multiplication factor
Shift Right by 12 = division by 212

Kernels and Parallel Branches

Some image processing operations apply multiple filtering operations to the same source image, and then combine the resulting
images. An example of this is shown in the Sync Variable Latency example, which subtracts the results of a 3x3 filter and a 5x5
filter. This operation is known as a Difference of Gaussians edge detection.

The Sync Variable Latency example describes an inefficient way of doing parallel branches with kernels:
Sapera APF Programmer's Manual

Key Concepts 59

There are two Kernel::KernelCreate functions, each consuming some of the FPGAs block RAM to internally buffer
lines.
Since the KernelCreate function has a variable latency, the resulting branches must be synchronized through a
StreamControl::BranchSync function. A Memory::LineBuffer function must also be added to prevent a dead-lock (see
the Synchronization of parallel branches section for more details).

A better way of implementing parallel branches is shown in SyncVariableLatencyOps_improved.apf. It performs the exact same
operation as SyncVariableLatencyOpf.apf but is more efficient in several ways:
The KernelCreate function is instantiated only once to create a 5x5 kernel, which reduces the usage of the FPGAs block
RAM.
Since the parallel branches only contain fixed-latency functions, it does not require a BranchSync function. The two
branchess output are directly fed to the Subtract function.
Since no BranchSync function is used, there is no need to provide a LineBuffer function.

In general, the Kernel::KernelExtract function is useful when there are parallel branches that use different kernel dimensions. The
Median Pixel Replacement example also demonstrates the use of the KernelExtract function used to extract a 1x1 kernel (that is, a
single pixel).

Sapera APF Programmer's Manual

Key Concepts 60

Color Processing
There are two typical scenarios for color processing:
1- The camera outputs RGB pixels. In this case, the Image I/O::CameraIn functions parameter LinkFormat must be set to
rgb24x2, indicating that on each of the FPGAs clock cycles, two RGB24 (or RGB888) pixels are output by the Image
I/O::CameraIn function.

2- The camera uses a Bayer color filter pattern to obtain color information. In this case, the Image I/O::CameraIn
functions parameter LinkFormat will be gray8x8 meaning that on each of the FPGAs clock cycles, eight MONO8
pixels are received. These pixels must be converted to RGB images using Bayer interpolation as demonstrated in the
Bayer example.

Sapera APF Programmer's Manual

Key Concepts 61

Extracting / merging color channels

Some functions directly process color pixels. For example, the Color::ColorMatrix3x3 function applies a multiplicative matrix on
the RGB pixels at its input. However, most Sapera APF functions only operate on monochrome images. To use them to process
color images is to split the 3 color channels, as shown in the ColorSegment example:
1- The RGB pixels are first obtained from the cameras Bayer pattern.
2- The RGB image is split into 3 monochrome images, using the Color::ChannelSplit function. Each one of the
monochrome images represent information about one of the color channels (R, G or B).
3- Each one of the color channels is processed separately as a monochrome image.
Color space conversions
The RGB color space is useful for displaying color images, but other color spaces are more useful for processing. For example,
the YUV color space makes a distinction between a color pixels luminance information (Y channel) and its color information (U
and V channels). The YUV Processing example shows how the YUV color space can be used to apply a look-up table to the
color pixels luminance while leaving the color information untouched:
1- The RGB pixels are first obtained from the cameras Bayer pattern.
2- The RGB pixels are converted to the YUV color space using the Color::RGBtoYUV function.
3- The resulting YUV image is split into 3 monochrome images, using the Color::ChannelSplit function. Each one of the
monochrome images represent information about one of the color channels (Y, U or V).
4- The Y image is processed through the Math::ApplyLUT function. The ApplyLUT can be used to implement any
processing by changing the contents of the look-up table. For example, it can apply a gamma correction to improve the
contrast of dark pixels for better display on a LCD screen.
5- The Y, U and V channels are merged back together using the Color::ChannelMerge function.
6- The YUV color pixels are converted to RGB color space using the Color::YUVtoRGB function, to be transferred and
displayed on the host computer.

Sapera APF Programmer's Manual

Key Concepts 62

Using Buffers
Some processing algorithms require images to be stored to external memory. This is done using the Memory::FrameBuffer
function. This function provides an interface to the external memory banks on the framegrabber.
The Xcelera-CL VX4 has five memory banks which are available to Sapera APF:
Memory
type

# of memory
banks

Size (MB)

Equivalent bus
width (bits)

DDR
RLDRAM

1
4

512
32

128
32

Maximum read+write
bandwidth per bank
(MB/s)
1000
200

Access to these external memory banks is optimal if the total number of bits per FPGA clock is the same as that memory banks
bus width. This is shown in the Simple Buffer DDR and Simple Buffer RLDRAM examples. In both cases, the images to buffer
are in the gray8x8 format (that is, 8 x 8-bit grayscale pixels per clock), which gives 64 bits of data for each of the FPGAs clock
cycles. There is a difference in how these pixels are buffered to external memory, depending on the type of memory bank being
used:
SimpleBufferDDR: images are buffered to DDR memory bank, which has an equivalent bus width of 128 bits. The
StreamControl::Parallelize function is used to increase the number of PixelsPerClock to 16; this has the effect of
increasing the number of bits per clock cycle to 128, which is the same as the DDRs bus width. This allows the pixel
stream to efficiently use all the DDRs bandwidth. After pixels have been read from memory, they are available at the
output of the Memory::FrameBufferfunction. The StreamControl::Serialize function is used to reduce the number of
PixelsPerClock back to 8 so the pixels can be transferred to the host computer.

SimpleBufferRLDRAM: images are buffered to one of the RLDRAM memory banks, which have an equivalent bus
width of 32 bits. The StreamControl::Serialize function is used to decrease the number of PixelsPerClock to 4; this has
the effect of increasing the number of bits per clock cycle to 32, which is the same as the RLDRAMs bus width
allowing the pixel stream to efficiently use the RLDRAMs bandwidth. After pixels have been read from memory, they
are available at the output of the Memory::FrameBuffer function. The StreamControl::Parallelize function is used to
increase the number of PixelsPerClock back to 8 so the pixels can be transferred to the host computer.

Facilitating the FPGA Place and Route

When a given design uses a large amount of FPGA resources, it can be helpful to add a Directives::PixelBuffer function before
and/or after a Memory::FrameBuffer function. This improves the probability that the FPGA place-and-route tool is able to
successfully perform its task.

Sapera APF Programmer's Manual

Key Concepts 63

Recursive Functions
One restriction listed in the Connection Rules section is that a given design should contain no feedback loop. This restriction
effectively would effectively prevent the implementation of recursive functions, one example being the recursive average:
Out[n] = A*Out[n-1] + B*In[n]

(where A + B = 1)

Here, to compute the nth output frame, access is needed to the (n-1)th output frame which implies that a given output image must
be fed back to the designs input for the next frame a feedback loop.
The way to bypass this restriction is to use the Image I/O::RecursiveIn and Image I/O::RecursiveOut functions, as demonstrated
in the Recursive Average example, shown here in a modified version:

Those two functions work in pair to create a hidden feedback loop - the pixels sent to the Image Image I/O::RecursiveOut
function become available at the output of Image I/O::RecursiveIn function. This allows the current output image to be stored in
memory and fed back into the design as an input for the next frame.

Sapera APF Programmer's Manual

Key Concepts 64

Changing image dimensions

Normally, Sapera APF automatically computes the maximum dimensions of the images that a given function can output.
However, the Geometry Functions can be used to change these image dimensions. The Subsampled Processing example
demonstrates how the Geometry::DownSample function reduces the output image dimensions by a factor of 4 with regard to the
input dimensions:.

For some functions, Sapera APF does not automatically compute the output dimensions; for example the Color::BayerToRGB
function. To demonstrate, this function can be added to the Bayer example by inserting it after the PixelControl::KeepMSB
function and adding extra Image I/O::FrameOut functions so that all outputs are connected:

Sapera APF Programmer's Manual

Key Concepts 65

The maximum dimensions at the input of the RGBtoYUY2 function are 8192 x 4096, but the maximum dimensions at the outputs
have incorrectly been set at 1024 x 1024. It is the users responsibility to manually initialize those values. In this particular case,
since the output is in the YUY2 (or YUYV) pixel format, the maximum dimensions should be set to 4096 x 2048, for each one of
the outputs:

Sapera APF Programmer's Manual

Key Concepts 66

Using signals
Sapera APF does not handle only images in the frame grabber, but also allows access to the frame grabbers various I/O pins. For
example, on the Xcelera-CL VX4, Sapera APF has access to the following I/Os:

4x general-purpose inputs

2x frame trigger inputs

4x general-purpose outputs

4x Camera Link camera control outputs (CC1 to CC4)

1x strobe output

General purpose signal processing

Sapera APF has a number of functions that can read, manipulate and output signals, and they are connected the same way image
processing functions are connected. A simple example which uses the general-purpose inputs and outputs is Read/Write General
Purpose IOs:

The Signal I/O Functions functions are used to physically monitor the current status of the frame grabbers generalpurpose input pins. In this example, the GPI functions are directly connected to Signal I/O::SignalRead functions which
allow the host application to read the status of those input pins, by getting the value of a read-only parameter. Other
functions could have been connected between the GPI functions and the SignalRead functions to perform various
operations, for example, detect rising edges, measure pulse widths, count pulses, and so forth.

Similarly, the Signal I/O::SignalWrite function can be used by the host application to set a signal status, which is
physically written to the frame grabbers general-purpose output pins via the Signal I/O::GPO functions. Other functions
can be used to perform various operations, such as generating pulses of varying width or clocks of varying frequency,
and so forth.

Sapera APF Programmer's Manual

Key Concepts 67

Camera signals: CC1 to CC4

In the Camera Link protocol, there are four dedicated signal lines which the framegrabber can use to control the camera: CC1 to
CC4.
On Teledyne DALSA frame grabbers, those four signal lines are usually driven by the FPGAs standard logic, based on standard
acquisition parameters that can configured and tested using the Sapera CamExpert tool. Sapera APF introduces the possibility of
generating the CC1 to CC4 signals based on custom user-defined logic:

A simple example of custom camera signals is in CC1 Variable Period and Variable Width:

This design assumes that the camera is in a mode where its exposure is triggered by its CC1 input. The design drives the CC1
signal with a clock with controllable period, using pulses of controllable width. The clocks period determines the cameras
frame rate, and the pulse width determines the cameras exposure time. For convenience, the general-purpose output #0 is driven
with the same signal as CC1, so it can be measured on the framegrabbers connector pins with an oscilloscope.
To make sure that it is Sapera APFs custom FPGA logic that drives the CC1 line (instead of the standard logic configured by
Sapera CamExpert parameters), one of the parameters of the Image I/O::CameraIn function must be modified. Here, since it is the
CC1 line that gets driven by custom logic, the CC1Ctrl parameter must be set to 1:

Sapera APF Programmer's Manual

Key Concepts 68

Refer to the Image I/O::CameraIn reference description for more details.

Frame triggers and line triggers

The Xcelera-CL VX4 board has frame trigger and line trigger inputs which are handled in a special manner:
Line triggers

Line trigger inputs are typically used with a shaft encoder to adapt image acquisition to the actual speed of a moving web
or conveyor belt.

In the Xcelera-CL VX4 I/O diagram, the line trigger inputs are shown as ShaftA and ShaftB.

Line triggers are not available in Sapera APF. Therefore, they are always configured using standard parameters that can
be set in Sapera CamExpert.

Frame triggers

The frame trigger inputs are used by the standard Camera Link front-end logic to generate the camera signals CC1 to
CC4. The exact behavior can be configured by standard Sapera LT parameters in Sapera CamExpert.

Frame triggers are not automatically sent to the front-ends standard logic. To add support for external frame triggers, a
Sapera APF design must include a path from Signal I/O::FrameTrigIn functions to Signal I/O::FrameTrigOut, as shown
in the External Frame Trigger example. This example also shows how to implement custom behavior; here it is reducing
the frequency of the frame triggers using the Signal I/O::FreqReduce function:

Sapera APF Programmer's Manual

Key Concepts 69

Signal processing vs image processing

An aspect to notice in the examples mentioned so far is that there are two separate sections: one handles images, and the other
handles signals. In the External Frame Trigger example, the image processing section and the signal processing section are
separate and do not interact:

Other examples show how the image processing domain and the signal processing domain can affect each other, which allows
two different scenarios:
1.

Output signals can be driven according to the contents of images;

2.

Images can be modified based on the status of input signals.

The Saturation Detection example demonstrates the 1st scenario. In this design, the Statistics::HorizontalMax function is used the
to determine the maximum pixel value found in a given line. If this maximum value is greater than a certain maximum
(determined by the Number parameter of the Boolean::GreaterOrEqualVal function), then a general-purpose output is set to
high; otherwise it is driven to low. This can be used to physically indicate to an external device that the lighting is too intense.

The main function of interest in this example is Signal I/O::PixelToSignal. This function allows information to pass from the
image processing domain to the signal processing domain. Looking at properties at the input and the output of the PixelToSignal
function, we can see that the DataType value has changed from Image to Signal:

Sapera APF Programmer's Manual

Key Concepts 70

As described in the Link Properties section, the data passed between functions has a property named DataType which describes
how data is synchronized. If a link between two functions can be thought of as a physical electronic bus between these functions,
then the DataType is the protocol that is used on this bus:
When DataType is Image, this indicates that alongside the pixel data, there are other wires on the bus which transmit
data valid, end-of-line and end-of-frame flags for each pixel. These flags are used to format the pixels into meaningful
images. In addition, there is a wire that transmits flow control information back to the source function.

When DataType is Signal, this indicates that the link just sends unsynchronized raw data. No synchronization is
performed.

Essentially, in order to generate signals based on image contents, the Signal I/O::PixelToSignal function is used to strip away the
unneeded synchronization signals. It is therefore easy to generate signals based on image contents, because the PixelToSignal
function only has to remove information.
The other scenario - changing image contents based on signal values - is also possible. This scenario requires additional steps
because it involves reintroducing synchronization signals. The example Signal To Pixel demonstrates this scenario, where the
output image contents is modified according to general-purpose input signals:

Sapera APF Programmer's Manual

Key Concepts 71

In this design, the pixel at a specific coordinate will be replaced by 255 if the general-purpose input at that time is high,
otherwise the pixel will be replaced by 0.
The design introduces two functions:

Signal I/O::SignalToPixel converts the DataType from Signal to Pixel.

StreamControl::PixelSync converts the DataType from Pixel to Image.

The pixels at the output of the Signal I/O::SignalToPixel function must be formatted into meaningful images. The
StreamControl::PixelSync function takes pixels and appends synchronization information based on an existing image. The image
thus generated can be combined with the image used for synchronization. In the Signal To Pixel example, there is a link between
the original image (at the output of BranchCreate) and the PixelToImage function. The pixels generated by the SignalToPixel
function are thus formed into an image that can then be combined with the original image, which in the current example is done
using the StreamControl::PixelMux function.

Sapera APF Programmer's Manual

Key Concepts 72

Using Sapera APF Firmware

After an FPGA firmware is routed with Sapera APF and uploaded to a supported frame grabber, it can be configured and used by
a host application using the Sapera LT API. The RTPro Demo distributed with Sapera APF is an example of a host application
that uses Sapera APF-generated firmware. It has been designed to be able to configure and use any design. Its source code is also
distributed so it can be used as a starting point for a custom application. Also, its executables (32-bits and 64-bits) are distributed
with Sapera APF and can be used for quick evaluation of a given design.

Configuring parameters
The Sapera LTs C++ class SapAcqDevice is used to configure the Sapera APF dynamic processing parameters. While the
SapAcqDevice class is usually used with Teledyne DALSA GigE Vision cameras, it can also be used to access a list of
parameters (also called features in GenICam terminology) as described by the GenICam-compliant XML file generated by Sapera
APF for a design.
Below is a list of the SapAcqDevice functions most often called by applications to configure a Sapera APF-generated firmware.
For more information on setting feature values using Sapera LT, refer to the Sapera LT documentation.
SapAcqDevice::GetFeatureCount
SapAcqDevice::GetFeatureInfo

SapAcqDevice::GetFeatureValue
SapAcqDevice::SetFeatureValue

Sapera APF Programmer's Manual

Used to obtain the number of features

Used to get information about a given feature, for example, its name, its data type, its
access rights ( read-write or read-only), the minimum and maximum accepted values,
and so forth.
Used to get a features value.
Used to change a features value.

Using Sapera APF Firmware 73

Configuring transfers
Before an application can configure the various data transfers, it may need to obtain information about the frame grabbers output
for its currently loaded firmware. This step is not necessary if the host applications developer already knows the configuration of
the various outputs of the design.
In the case of the RTPro Demo, it has been designed so that any firmware can be configured and used, without modifying the
source code or recompiling it. In this case, the features listed below can be used to adapt the application to any design. These
features are available in all firmware generated by Sapera APF. Please refer to the RTPro Demos source code for a more
complete description of the usage of the various features.
uProInputWidth,
uProInputHeight
uProInputFormat
dataStreamSelector

Width, Height, PixelFormat

widthMode, heightMode

uProOutputPortName
uProOutputPortType

The application should use these features to describe the dimensions and the format of the
images received from the camera. This serves 2 purposes:
- Validate if the dimensions and format are supported by this processing design;
- Determine the dimensions of the images at the processings output.
This feature can be used to determine the number of outputs of the processing design
(outputs are also called streams in the GenICam terminology). This feature determines
which output is described by the current values of the other features: Width, Height,
PixelFormat, uProOutputPortName, and uProOutputPortType.
Returns the dimensions and format of the memory buffer that should be allocated to receive
data at the output of the currently selected stream.
Can be used to manually override the Width and Height features. By default, widthMode
and heightMode are set to Default, and the Width and Height features are computed
according to the cameras output dimensions. In this case, the Width and Height features are
read-only. Changing widthMode or heightMode to Manual will set the related feature to
read-write, allowing the user to change the buffer dimensions.
Returns the name of the selected output stream, which is the name of the related FrameOut
function as it was set in Sapera APF.
Determines which C++ object must be used to receive the data at the currently selected
output stream.

Data transfers are established by enumerating a number of transfer pairs which describe the complete data path. All transfer
pairs involve Sapera LT C++ objects that derive from the SapXferNode base class: SapAcquisition, SapRTProXferNode, and
SapBuffer. The required transfer pairs depend on which FrameOut function was selected in Sapera APF to transfer data to the
host memory, as shown in the following example:

Sapera APF Programmer's Manual

Using Sapera APF Firmware 74

Typical frame grabber applications using Sapera LT have SapAcquisition and SapBuffer objects to configure the image
acquisition and transfer. For Sapera APF designs using the FrameOutRaw function, this also applies. Only firmware that includes
an Image I/O::FrameOutRaw output will be able to run with existing applications like CamExpert, Grab Demo, Sequential Grab
Demo, and so forth. These applications will only see the FrameOutRaw output.

For Sapera APF designs using multiple outputs (such as Image I/O::FrameOut2, FrameOut3, and FrameOut4), transfers are
established using a SapRTProXferNode object. Previously, the SapRTProXferNode class was used to configure all custom
processing on Teledyne DALSA frame grabberss FPGA; for firmwares generated with Sapera APF, it is only used to configure
transfers.

Sapera APF Programmer's Manual

Using Sapera APF Firmware 75

Sapera APF Programmer's Manual

Using Sapera APF Firmware 76

Sapera APF Introductory Exercises

Example Designs
Several example designs are provided within Sapera APF. In general, they tend to demonstrate the contents of the library while
teaching how to program designs. There are several advantages to using the examples:

An easy way to learn what functionality is available within the tools.

A large amount of code can be reused in your application.

Some examples are more complete and may be used as a starting point for your application.

To facilitate the learning curve, the following table gives an introductory list of example designs, ordered by increasing level of
difficulty:
Example Name

Concepts introduced

Pass Through

A first approach to Sapera APFs GUI with the simplest design. Shows image input and output,
function properties, link properties.

Simple Threshold

Chaining functions to get a simple linear sequence of functions, changing BitWidth.

Simple Processing

Parallel non-merged branches, multiple outputs.

Multiple Outputs

Kernel operations.

Bayer

Outputting color images, changing PixelsPerClock .

White Balance

Functions that process color images, simple per-component color processing, merged parallel
branches using only fixed latency functions.

ColorSegment

More complex per-component color processing.

Flat Line Correction

Look-up tables, processing that depends on the pixels coordinates.

Read/Write General Purpose IOs

Access to the general-purpose I/O pins on the frame grabber.

Saturation Detection

Driving general-purpose output pin based on image contents, difference between

DataType=Signal and DataType=Image.

CC1 Variable Period and Variable Width

Generating signals, driving CC camera control signals.

Sync Variable Latency

Using the BranchSync function to merge parallel paths that include variable-latency functions.

Sync Variable Latency Improved

A better way to implement merged parallel branches when using kernel operations.

GPI Select Processing Path

Modifying images according to general-purpose input pins, combining images using the
PixelMux function.

Recursive Average

Using RecursiveOut and RecursiveIn functions to implement a feedback loop.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 77

The following table provides a complete list of available examples.

Example Name

Description

Auto Gain

Implements an automatic gain control

Auto-Threshold

Implement an automatic thresholding algorithm

Bayer

Converts a Bayer image to RGB

ColorSegment

Converts a Bayer image to an HSI color image and then segments each color channel.

ExtractKernel

Demonstrates how to create multiple kernels from a single kernel.

Flat Line Correction

Implements a flat line correction

Frame Diff

Performs a frame difference operation.

Gaussian5x5

Applies a Gaussian 5x5 kernel.

JPEG RBG

Demonstrates how to perform JPEG compression

Lossless Compression

Demonstrates how to perfrom lossless compression using Paeth and Huffman encoding functions.

Median Filter

Applies a Median filter.

Median Pixel Replacement

Performs a median pixel replacement operation.

Morph Close

Performs a morphological close operation.

Morph Dilate

Performs a morphological dilate operation.

Morph Edge Detection

Performs a morphological edge detection operation.

Morph Erode

Performs a morphological erode operation.

Morph Open

Performs a morphological open operation

Multiple Outputs

Demonstrates multiple outputs using different processing.

Pass Through

Simple pass through design used to validate setup.

Recursive Average

Demonstrates how to perform a recursive operation.

Simple Buffer DDR

Demonstrates how to maximize transfer to DDR frame buffer.

Simple Buffer RLDRAM

Demonstrates how to maximize transfer to DDR frame buffer.

Simple Processing

Implements a simple processing operation.

Simple Threshold

Implements a simple thresholding operation.

Sobel Edge

Performs Sobel gradient filtering in both the X and Y direction.

Subsampled Processing

Performs processing on a subsampled image.

Sync Memory Banks

Synchronizes memory banks in different branches.

Sync Variable Latency

Synchronizes branches with variable latencies.

Sync Variable Latency Improved

Synchronizes branches with variable latencies using a more efficient implementation.

Variable Output Dimensions

Format output from sources with variable dimensions

White Balance

Performs white balance correction.

YUV Processing

Demonstrates how to convert an RGB image to YUV format to perform processing on a YUV
component.

IO Examples
CC1 Variable Period and Variable Width

Demonstrates how to use a clock generator to create a signal of varying length and period to drive
a CC1 and general purpose IO.

External Frame Trigger

Demonstrates how to implement external frame triggers.

GPI Select Processing Path

Demonstrates hoe to use a general purpose input to switch between processing paths.

GPI To CC1

Demonstrates how to use a general purpose input to drive a CC1 output.

Read/Write General Purpose IOs

Demonstrates how to read/write general purpose IOs.

Saturation Detection

Performs a saturation detection operation, sending a general purpose output signal in response.

Signal To Pixel

Demonstrates how to convert a signal to pixel image format.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 78

Auto Gain
The Auto Gain example (AutoGain.apf) automatically computes a gain factor to be applied to incoming pixel values so that the
images average value reaches a determined target.
To compute a frames average pixel value, the Statistics::FrameSum function
provides a cumulative summation of all the pixel values received so far in the
current image. The Math::Constant function is used to provide a constant 0 to
the FrameSums ClrI input so that this sum only returns to 0 at the beginning
of a frame.
The last pixel at the output of the FrameSum is the cumulative sum for the
whole input frame. This is the pixel that is used to compute the whole frames
average value. After this last pixel value is divided by the number of pixels in
the image (using Math::MultiplyByVal and PixelControl::KeepMSB (see
below for further explanation), it gives the average pixel value for the whole
frame.
The StreamControl::PixelCarry function takes this last pixel value and
generates a whole image with the same value. This image is in turn used to
compute a gain factor for the next input frame in essence, input image N is
used to compute a gain factor for image N+1. This approximation to
computing the gain is appropriate when the image intensity does not vary
much from one frame to the next.
To divide the sum of pixels by the number of pixels, an FPGA-friendly
approach is used (similar to the one decribed in Normalizing the output in
the Computing Convolutions section), which is to multiply by a scaling factor
then to divide by a power of 2. Division by a power of 2 is done by the
PixelControl::KeepMSB function, which keeps the upper 8 bits out of the 32
bits at its input. This operation is equivalent to applying a right-shift of 24
bits, or a division by 2^24.

The scaling factor required for Math::MultiplyByVal can be calculated so that the average pixel value is computed correctly:
Average =

Sum of pixels
Number of pixels

K=

2^24
Sum of pixels

Sum of pixels
width*height

K * Sum of pixels
2^24

For example, if the input images are 4096x4096, the required scaling factor in MultiplyByVal is:
K = 2^24 / (4096*4096) = 1
If the input images are 1024x1024, the required scaling factor in MultiplyByVal becomes:
K = 2^24 / (1024*1024) = 16

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 79

The average pixel value is carried over every pixel in the next frame by the CarryPixel function where is it used to compute a gain
factor to be applied to every pixel in the next input frame. This gain is equal to the target average divided by the computed
average.
Computing a gain with a few decimal places would usually require implementation of floating-point division, which requires a
large amount of resources on the FPGA. Instead an FPGA-friendly approach is taken: first multiply the divisions numerator by
2^8, then apply the resulting gain factor to the input images pixels, with the result divided back by 2^8.
The PixelControl::SelectFromParallel functions are used to reduce the PixelsPerClock at the input of the Math::Divide function,
which is FPGA resource intensive. Since all pixels generated by the PixelCarry and Constant functions are identical, we can
perform the division for only 1 out of the 4 identical pixels. The resulting value can then be duplicated to obtain a stream with
PixelsPerClock=4 where all 4 pixels are identical.

Auto-Threshold
The Auto-Threshold example (AutoThreshold.apf) performs automatic thresholding by comparing the input image to a frame sum
average.

The average pixel value is computed as is shown in the Auto Gain example. Similarly, an image is
created by PixelCarry where all pixels take the previous frames average pixel value.
The Boolean::GreaterOrEqual function compares the current frames pixels to the previous frames
average pixel value. If the current image pixel is greater than or equal to the average, the output is
True (or 1). This approximation for computing the threshold value is appropriate if the average
image pixel value does not vary much between frames.
The Math::MultiplyByVal scales the binary output to an 8-bit width for display.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 80

Bayer
The Bayer example (Bayer.apf) demonstrates how to use a kernel to perform a conversion from Bayer to RGB.

The StreamControl::Serialize function reduces the number of pixels per clock of the input link from 8 to
2. This is done since the Image::FrameOut2 output function uses the rgb24x2 format, therefore the
maximum number of pixels the PCIe bus can transfer per clock cycle is 2 RGB pixels. In general it is
recommended that this serializing, or reducing of the number of pixels per clock, be done as close to the
source as possible to reduce resource usage.
The Kernel::KernelCreate is used to to buffer the incoming lines and create a 3x3 kernel, in order to
perform interpolation on the Bayer images mosaic.
The Color::BayerToRGB function performs the color conversion. Since the output conversion has a bit
width of 30, the PixelControl::KeepMSB operates on each channel individually to convert the image
back to rgb24x2.
To get better interpolation, the Color::BayerToRGB5x5 function could have been used instead, but it
would require the output of the KernelCreate function to be changed from 3x3 to 5x5.

CC1 Variable Period and Variable Width

The CC1 Variable Period and Variable Width example (CC1VarPeriodVarWidth.apf) demonstrates how to generate a camera
control signal (CC1) and a general-purpose output using the Signal I/O Functions. The CC1 output can be used to control the
camera exposure while the general-purpose output could control a strobe, for example.
The left side of the design presents a simple camera passthrough, while the right side generates the signals.
To first generate a periodic signal, a Signal I/O::Clock function is used. Control signals to the clock are provided by two Signal
I/O::SignalHigh functions, so that the Clock function is based on thethe FPGAs design clock (100 or 112 MHz, depending on the
front-end chosen). . The Clock functions output period will determine the frame rate of the camera.
The Signal I/O::EdgeToShortPulse function generates a short pulse at every rising edge of theClock functions output. This pulse
width is then increased using Signal I/O::PulseWidthIncrease, which allows the width to be dynamically adjusted by the host
application. This pulse width will determine the cameras exposure time. The PulseWidthIncrease function also requires a
control signal, provided by a Signal I/O::SignalHigh function which sets the function to be based on the FPGAs design clock.
The Signal I/O::SignalInvertCond function allows the polarity of the pulses to be dynamically changed by the host application
from active-high to to active-low.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 81

ColorSegment
The ColorSegment example (ColorSegment.apf) demonstrates how apply processing separately on each channel of a color image.
The Bayer filtered image is first converted to RGB. The Color::ChannelSplit function then splits the RGB image into separate
channels.
Each image at the output of ChannelSplit is a monochrome image; in the current example, all 3 images are binarized using the
Boolean::InRange function. Boolean::BitwiseAnd is used to identify pixels who have all 3 channel values within the defined
range.
The Math::MultiplyByVal function is used as a gain to multiply the 1-bit pixel stream by 255 to enable display of the thresholded
binary image.
The StreamControl::Parallelize function is used to increase the PixelsPerClock from 2 to 8 pixels per clock to allow transfer of
the stream to the host computer.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 82

External Frame Trigger

The External Frame Trigger example (ExternalFrameTrigger.apf) demonstrates how to implement custom modes for handling
external frame triggers. The Signal I/O::FrameTrigIn0, FrameTrigIn1 functions provide access to the frame grabber input triggers.
The Signal I/O::FreqReduce functions allows the the input to be downscaled dynamically by the host application before being
sent to the frame grabber front-end using Signal I/O::FrameTrigOut0, FrameTrigOut1. Refer to the Camera signals: CC1 to CC4
section for details on how the frame grabber routes frame trigger signals.

ExtractKernel
The ExtractKernel example (ExtractKernel.apf) demonstrates how to use the Kernel::KernelExtract function to create new kernels
from a subset of a larger kernel. The KernelExtract function provides an efficient way to implement parallel branches that use
different kernel dimensions..
In this example, an image is binarized using the Boolean::GreaterOrEqualVal function to perform thresholding. The input stream
is buffered for kernel processing using a 7x7 kernel, which is the largest of the 4 required kernel dimensions.The image stream is
duplicated into 4 separate branches using the StreamControl::BranchCreate function. Each stream then has a different dilation
kernel applied. The Kernel::BinaryDilate function is used since the input image is binary. The 1x1 kernel functions as a
passthrough.
The StreamControl::FrameMux function is then used to select which processing kernel result to transfer at run-time.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 83

Flat Line Correction

The Flat Line Correction example (FlatLineCorrection.apf) uses lookup tables that apply a gain and offset correction to the
incoming pixels based on the pixel position (that is, the X coordinate) .

The design uses the PixelControl::XPos function to get the X coordinate of the
incoming pixels. This value is then used as an index into look-up tables that
determine the required gain and offset coefficients to be applied at this X
coordinate. Those coefficients are stored in the Math::ApplyLUT functions.
First the offset value is subtracted from the original pixel value, fed by a separate
branch, using the Math::Subtract function.
The Math::SaturateLow function prevents negative values at the output of the
subtraction, while the Directives::ReinterpretSign is used to remove the sign bit by
changing the output from signed to unsigned (the original stream format).
The PixelControl::KeepLSB function returns the stream to the original 8-bit width
format.
The gain is then applied. Instead of applying a floating-point multiplication, the
functions Math::Multiply and Math::ShiftRight are combined to implement fixedpoint multiplication. The precision of this multiplication depends on the actual bit
shift implemented by Math::ShiftRight, and the values in LUT_Gain must be
computed accordingly. For example, if ShiftRight shifts values by 5 bit positions,
the 8-bits gains stored in LUT_Gain will include 5 bits of precision after the
decimal point. The remaining 3 bits of precision are the decimal point give the
maximum gain factor; a gain value of 255 would then corresponds to a
multiplication by nearly 2^3 = 8.The PixelControl::KeepLSB functions is used to
return the stream to its original format so it can be transferred to the host.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 84

Frame Difference
The Frame Difference example (FrameDiff.apf) performs a frame difference calculation by subtracting the previous (or last)
image from the current image.

The StreamControl::FrameInsertInitial function is used to pause its input stream and supply an
initial image for the StreamControl::BranchSync function. This is necessary since the first input
frame has no previous image to perform frame differencing. The StreamControl::FrameInsertInitial
function will pause its Rec input for one frame, which implies that the frame on this input must be
buffered to external memory using a Memory::FrameBuffer function. While this input is paused,
StreamControl::FrameInsertInitial will output a replacement image based on the dimensions of
the image received on its Org input. This image can either be the same image as received on the
Org input, or an image with a constant pixel value.
Since the StreamControl::FrameInsertInitial function has a variable latency, the
StreamControl::BranchSync function is required so the two branches (the current and the
previous images) can be processed together.
After the difference is computed using the Math::Subtract function, the Math::AbsoluteValue
function is used to compute the magnitude of the signed pixel values resulting from the
substraction
TheBoolean::GreaterOrEqualVal function thresholds the results to keep only pixel differences that
are greater than a configurable parameter value that determines how sensitive the processing is to
differences.
The Math::MultiplyByVal function is used to multiply the 1-bit pixel stream by 255 to enable
display of the thresholded binary image as an 8-bit image.

By default the Image I/O::CameraIn function is configured for input images with maximum dimensions of 2048x1024 and the
size of the Memory::FrameBuffer function in the branch is set to 2048x1024. If the input resolution is modified, the size of the
Memory::FrameBuffer function may have to be adjusted, and should be set to the same size as the input image.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 85

GPI Select Processing Path

The GPI Select Processing Path example (GpiSelectProcessingPath.apf) demonstrates how to convert a general purpose input
data signal into image data, to use to switch between the original image and the processed image.

The Signal I/O::GPI0 function is used to access the frame grabber general purpose
input. This input signal is then converted to an unsynchronized stream of pixels using
the Signal I/O::SignalToPixel function. The StreamControl::BranchSync function is
then used to synchronize this pixel stream with the images received from the camera.
Since the BranchSync function requires both inputs to be of the same type, the
StreamControl::Parallelize is used to increase the pixels per clock to 8 to match the
format of the output of the Image I/O::CameraIn function.
The camera image output is then duplicated using StreamControl::BranchCreate to
create two parallel processing branches. In this case, one of the branches isinverted
image with a Boolean::BitwiseNot function while the other branch is left unmodified.
The resulting two images (the original camera output or the inverted image) can then be
selected using the general purpose input as the switch in the StreamControl::PixelMux
function.

GPI To CC1
The GPI To CC1 example (GpiToCC1.apf) is a simple example showing how the Signal I/O::GPI0 function can be used to drive a
Signal I/O::CC1 output. Since the CC camera control signals are hidden inside the Camera Link cable, they are not easily
accessible and cannot be driven by an external device. By connecting the GPI0 and CC1, this signal can be made accessible as an
input on the frame grabbers external connector.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 86

Gaussian5x5
The Gaussian5x5 example (Gaussian5x5.apf) applies a Gaussian 5x5 filter to the image. It demonstrates how to normalize the
convolution using a multiplication (Math::MultiplyByVal) and a Math::ShiftRight operation instead of using the resource
intensive Math::Divide function.

TheKernel::KernelCreate and Kernel::Convolution functions are used to create a 5x5 Gaussian kernel
with the following coefficients:

The sum of the coefficients in the kernel is 273.

To normalize the result, the output must be divided 273. The Math::MultiplyByVal function and a
Math::ShiftRight function can be used to perform an approximation of the division.
The Math::ShiftRight functions as a division by factors of 2, depending on the number of bits that are
shifted. The value of the shift right is chosen depending on the divisor; if it is too small the division
approximation may be too rough and not accurate enough. In this example, a shift right of 12 provides
an accurate enough approximation.
The multiplication factor to be used in Math::MultiplyByVal can be determined by taking the divisor and multiplying it by 2^12,
and rounding it to the nearest integer value:
(1/273)*(212) = 15.003663
The approximation of 1/273 thus becomes 15/4096, and is easier to implement in the FPGA:
1
273

15
4096

Multiplication factor
Shift Right by 12 = division by 212

The convolutions output links BitWidth is set to17 (217 = 131072) in order to have the capacity to handle the maximum possible
value (273 x 255 = 69615).
The multiplication factor 15 requires 4 bits and increases the output BitWidth to 17+4=21.
The shift right by 12 leaves a bit width of 21-12=9. The Math::SaturateHigh limits the possible ouput to 255 and the
PixelControl::KeepLSB returns the image to an 8-bit width for display.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 87

JPEG RBG
The JPEG RGB example (JPEG_RGB.apf) demonstrates how compress RGB images using JPEG.

The RGB output from the Image I/O::CameraIn is sent to the

StreamControl::BranchCreate to create two image streams.
The left branch streams a raw, unprocessed RGB directly to the Image
I/O::FrameOutRaw function.
The right branch uses the StreamControl::BranchEnable function as a valve to enable
or disable the branch image stream. This function is enabled or disabled using the
BranchEnable parameter available on the host application.
When the compression branch is enabled, the Color::RGBtoYUY2 function takes two
consecutive input RGB pixels and generates two monochrome pixels with luminance
information (the Y outputs) and two monochrome pixels with chrominance outputs (the
U and V outputs). Those channels are then packed to 32-bits pixels using
PixelControl::ParallelMergeto conform to the input format required by the
JPEGColor4P4k function. Note that the links between RGBtoYUY2 and PixelMerge
are crossed so that the YYUV outputs become YUYV.
The output of the compression has a PixelsPerClock=1, which is then returned to
PixelsPerClock = 8 using the StreamControl::Parallelize. The
StreamControl::RectangleReshape function ensures that the output has consistent
dimensions as required by the Image I/O::FrameOut2 function.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 88

Lossless Compression
The Lossless Compression example (LosslessCompression.apf) demonstrates how to create a two branch configuration that
allows switching between a raw image output branch and a slower output branch that produces compressed images.

The grayscale mono 8x8 output from the Image I/O::CameraIn is sent to the
StreamControl::BranchCreate to create two image streams.
The right branch uses StreamControl::BranchEnable function as a valve to enable or
disable the branch image stream. This function is enabled or disabled using the
BranchEnable parameter available on the host application.
The StreamControl::Serialize reduces the PixelsPerClock of the stream from 8 to 4 so it
can be compressed with the Paeth predictor and the Huffman encoding (which both only
support input with PixelsPerClock=4). Since the right-hand branchs maximum
bandwidth is reduced, enabling it will reduce the maximum bandwidth of the left-hand
branch as well.
When the compression branch is enabled, the DataReduction::Paeth8bit4P8k function
applies a Paeth prediction filter to the image stream. The distribution of the pixel values at
the output of the Paeth predictor should show a peak centered around 0; this result can
then be efficiently encoded with DataReduction::Huffman9bit4P to reduce the average
number of bits per pixel.
The DataReduction::Huffman9bit4P functions outputs 2 pixels of 64 bits per clock; this
output is then returned to gray8x8 format using StreamControl::Serialize and
Directives::ReinterpretPixelsPerClock functions. The StreamControl::RectangleReshape
function ensures that the output has consistent dimensions as required by the Image
I/O::FrameOutRaw2 function.

Median Filter
The Median Filter example (MedianFilter.apf) uses a kernel to apply a median filter using the Kernel::Median function. Note that
the StreamControl::Serialize is not strictly necessary, but saves FPGA resources when used. StreamControl::Parallelize is used to
format the stream of pixels back to gray8x8 so it can be sent to the host using the Image I/O::FrameOut2 function.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 89

Median Pixel Replacement

The Median Pixel Replacement example (MedianPixelReplacement.apf) compares the current pixel with the average of its
neighbors. If it is too different, it is likely a dead pixel, in which case it is replaced with the median filtered pixel.
The Kernel::KernelCreate function is placed before the
StreamControl::BranchCreate to reduce FPGA resource usage as the kernels in each
branch can use the same kernel buffer.
The second branch uses the Kernel::KernelExtract function to output the original
target pixel at the center of the kernel.
The third branch performs a neighborhood averaging operation using the
Kernel::Convolution.
The Math::Subtract function is then used to subtract this average from the original
pixel value. The Math::AbsoluteValue function is used to remove any negative
values resulting from the substraction.
The Boolean::GreaterOrEqualVal function output is used as the control signal for
the StreamControl::PixelMux function; if the subtraction between the original pixel
value and the average results in a difference greater than a certain threshold value,
the original pixel value is substituted by the result of the median filtering function.

Morph Close
The Morph Close example (MorphClose.apf) performs a morphological close operation on a binarized image thresholded using a
Boolean::GreaterOrEqualVal function. The close operation is done using a Kernel::BinaryDilate followed by a
Kernel::BinaryErode. The Math::MultiplyByVal function is used to multiply the 1-bit pixel stream by 255 to enable display of the
thresholded binary image as an 8-bit image.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 90

Morph Dilate
The Morph Dilate example (MorphDilate.apf) applies applies a Kernel::BinaryDilate to an image thresholded using a
Boolean::GreaterOrEqualVal function.

Morph Edge Detection

The Morph Edge Detection example (MorphEdgeDetect.apf) performs edge detection by comparing the results of a
Kernel::BinaryDilate and a Kernel::BinaryErode functions an image thresholded using a Boolean::GreaterOrEqualVal function.

The Boolean::BitwiseXor function is used to compare the results of the different operations;
when the dilate and erode operations produce opposite values, the pixel is considered as being on
the edge of an object, and is output as a white pixel in the resulting binary image.
The Math::MultiplyByVal function is used to multiply the 1-bit pixel stream by 255 to enable
display of the thresholded binary image as an 8-bit image.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 91

Morph Erode
The Morph Erode example (MorphErode.apf) applies a Kernel::BinaryErode to an image thresholded using a
Boolean::GreaterOrEqualVal function. The Math::MultiplyByVal function is used to multiply the 1-bit pixel stream by 255 to
enable display of the thresholded binary image as an 8-bit image.

Morph Open
The Morph Open example (MorphOpen.apf) performs a morphological open operation on a binarized image (thresholded using a
Boolean::GreaterOrEqualVal function). The open operation is done using a Kernel::BinaryErode followed by a
Kernel::BinaryDilate.
The Math::MultiplyByVal function is used to multiply the 1-bit pixel stream by 255 to enable display of the thresholded binary
image as an 8-bit image.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 92

Multiple Outputs
The Multiple Outputs example (MultipleOutputs.apf) demonstrates how to create four image outputs using the
StreamControl::BranchCreate and Image I/O::FrameOutRaw, FrameOut2, FrameOut3, and FrameOut4 functions. The output
images include the unprocessed raw image, with different processing operations performed on the other three images. The
processing includes a simple binary threshold using a Boolean::GreaterOrEqualVal function, a morphological operation using a
Kernel::Median function, and a simple inversion using a Boolean::BitwiseNot function.

Pass Through
The Pass Through example (PassThrough.apf) is a minimal design that simply illustrates how the camera input Image
I/O::CameraIn function connects to the Image::FrameOutRaw function to output the image.

The Pass Through design can be used to test the Sapera APF installation and ensure that the Xilinx package has been properly
installed to generate firmware. The generated firmware can then be loaded on the frame grabber and the RTPro demo used to
validate the camera acquisition and setup.
The CameraIn properties can be changed to reflect the actual acquisition setup.

To change the target Camera Link front-end, click on Main in the Program window and select the required platform.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 93

Read/Write General Purpose IOs

The Read/Write General Purpose IOs example (ReadWriteGPIOs.apf) demonstrates the functions that allow an application to
read (Signal I/O::SignalRead) the status of the general purpose inputs (Signal I/O::GPI0, GPI1, GPI2, GPI3), and to set (Signal
I/O::SignalWrite) the status of the general purpose outputs (Signal I/O::GPO0, GPO1, GPO2, GPO3).

Recursive Average
The Recursive Average example (RecursiveAverage.apf) demonstrates how to perform a recursive average operation. A recursive
average takes the average of the current frame and the previous output frame.
In general, with custom FPGA processing data must always go forward since the
FPGA must synchronize functions, therefore feedback loops are not permitted.
However, the Image I/O::RecursiveOut and Image I/O::RecursiveIn functions can
be used to resend the output frame to the processing loop without losing
synchronization.
The output frame is sent to both the Image::FrameOut2 and the Image
I/O::RecursiveOut functions. The RecursiveOut function sends the output frame
to the Image I/O::RecursiveIn function. The RecursiveIn frame must be buffered
to store the current result while waiting for the next frame. However, the current
image from the CameraIn function and the previous frame from the RecursiveIn
function are not synchronized, therefore the StreamControl::BranchSync function
is required. Since the BranchSync requires 2 image inputs, the
StreamControl::FrameInsertInitial function is needed to provide an initial frame to
the BranchSync function until the RecursiveIn receives its first frame from the
RecursiveOut function. If an intitial frame is not presented, the BranchSync will
pause the CameraIns branch until data from the RecursiveIn branch is provided;
in doing so it prevents data from reaching the RecursiveOut function causing a
deadlock.
Note that Sapera APF does not currently support simulation of recursive designs.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 94

Saturation Detection
The Saturation Detection example (SaturationDetection.apf) sends a signal to a general output when image saturation is detected.
A StreamControl::BranchCreate function sends the original image directly to an Image I/O::FrameOutRaw function, and to the
processing branch. PixelControl::SelectFromParallel is used to reduce the PixelsPerClock from 8 to 1 by keeping only one out of
the eight pixels. This allows for reduction in FPGA resource usage while keeping the same maximum bandwidth at the input.
This method is appropriate because later processing does not need to process all 8 pixels.
The Statistics::HorizontalMax computes the maximum pixel value found in each line in the frame. HorizontalMax has an input to
determine if the computed maximum should be reset back to 0. Since a reset is not wanted, this input is supplied with a constant
value 0, provided by the Math::Constant function. In turn, the Math::Constant function needs to know the dimensions of the
image it must generate, the original image is sent to provide the image protocol (dimensions an synchronization).
The IsMaxO output indicating a new maximum is not required and is therefore terminated by a StreamControl::Trash function,
while the data output is compared to the maximum acceptable pixel value specified by the Boolean::GreaterOrEqualVal function,
in this case 250. The boolean binary output is then converted by a Signal I/O::PixelToSignal function to a signal. This signal can
then be accepted as an input by the Signal I/O::SignalInvertCond, which provides control over the signal polarity, to send to the
Signal I/O::GPO0 function to drive the general purpose output when saturation is detected.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 95

Signal To Pixel
The Signal To Pixel example (SignalToPixel.apf) demonstrates how to perform a pixel replacement operation using a pixel
created from a general purpose input signal.
The Signal I/O::GPI0 function provides access to the general purpose input signal on the frame grabber. This signal is converted
to an unsynchronized pixel stream using the Signal I/O::SignalToPixel. Timing information from the image stream output by the
camera is applied to this pixel stream by the StreamControl::PixelSync function so that the pixel stream can now be treated as an
image and accepted by functions that require image data format inputs. The StreamControl::Serialize function is first applied to
the camera output to reduce the pixels per clock output to the same as that of the pixel stream.
The functions in the ReplacePixelCondition group use the PixelControl::XPos and PixelControl::YPos functions to extract the X
and Y coordinates of the pixel. If either coordinate is equal to 0, the Boolean::EqualVal function returns True (1). If both
coordinates are 0, then the Boolean::BitwiseAnd returns true (1) and activates the switch control link of the
StreamControl::PixelMux function, in effect replacing the first pixel of a frame with the current status of the general purpose
input at that time.
The StreamControl::Parallelize returns the image stream to the original format so it can be output to the host using the Image
I/O::FrameOutRaw function.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 96

Simple Buffer DDR

The Simple Buffer DDR example (SimpleBufferDDR.apf) demonstrates how to maximize the bandwidth to DDR memory when
using Memory::FrameBuffer. The StreamControl::Parallelize function increases the PixelsPerClock to 16 so that the output
reaches 128 bits per cycle (8-bit pixels x 16), which is adapted to the DDR memorys data bus for maximum throughput. The
StreamControl::Serialize reduces the PixelsPerClock back to 8 , the format required by the Image::FrameOutRaw function.

Simple Buffer RLDRAM

The Simple Buffer RLDRAM example (SimpleBufferRLDRAM.apf) demonstrates how to maximize the bandwidth to RLDRAM
memory when using a Memory::FrameBuffer. The StreamControl::Serialize function reduces the input pixels per clock to 4 so
that the output is 32 bits per cycle (8-bit pixels x 4), which is adapted to the RLDRAM memorys data bus for maximum
throughput. The StreamControl::Parallelize function increases the PixelsPerClock of the output back to 8, the format required by
the Image::FrameOutRaw function.

Simple Processing
The Simple Processing example (SimpleProcessing.apf) demonstrates how to use the StreamControl::BranchCreate function to
create a second image stream on which to perform processing ( a simple inversion using a Boolean::BitwiseNot function) while
outputting the original unprocessed image using the Image::FrameOutRaw function.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 97

Simple Threshold
The Simple Threshold example (SimpleThreshold.apf) is a minimal design that uses a Boolean::GreaterThanVal function to
perform a thresholding operation.

The Image I/O::CameraIn provides an input to the Boolean::GreaterOrEqualVal function with a BitWidth and PixelsPerClock
with a value of 8.

The output of the Boolean::GreaterOrEqualVal has a BitWidth of 1; pixel values greater than or equal to the specified value return
1 (True), otherwise the output is 0 (False).

The Math::MultiplyByVal is used to return the data stream to an 8-bit width for image display by multiplying by 255.
The important concept to understand is how the bit width changes between the input and output of different functions, and how to
modify this bit width when necessary.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 98

Sobel Edge
The Sobel Edge example (SobelEdge.apf) demonstrates how to use the Kernel::Convolution function to apply Sobel filters for
edge detection in both the X and Y directions.
The Kernel::KernelCreate function is used before the StreamControl::BranchCreate so
that the 3x3 kernel stream is shared by both branches instead of re-buffering the same
data separately.
The X and Y Sobel kernels are created in each branch using a Kernel::Convolution
function:
-1

-1

-2

-2

-1

The Math::AbsoluteValue function computes the magnitude of the signed values and
ensures that all values are positive. The PixelControl::KeepMSB function returns the
pixels back to BitWidth=8.
The StreamControl::FrameMux function can then be used to choose the Sobel
operation to display. The FrameMux allows the host application to select the image
stream to use at run-time. The function guarantees frame integrity by switching its
input only between frames no switch will occur in the middle of a frame.
The Math::MultiplyByVal function acts as a gain on the selected image to further
enhance the edge detection, making weaker edges more visible.
The PixelControl::KeepLSB function limits values to an image stream with an 8-bit
width for display.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 99

Subsampled Processing
The Subsampled Processing example (SubsampledProcessing.apf) demonstrates how to use the Geometry::DownSample function
to subsample an input image, perform a convolution processing operation.
By reducing both dimensions of the image by a factor of 4, the number of pixels to be processed is reduced
by a factor of 16. The reduced images can then be processed with a PixelsPerClock of 1 without reducing
the maximum bandwidth at the input. This allows running an operation which would be costly in terms of
FPGA resources in the current example, a 7x7 gray-scale convolution.The Math::MultiplyByVal and
Math::ShiftRight functions are used to approximate a division operation to normalize the
Kernel::Convolution function:

1
49

84
4096

Multiplication factor
Shift Right by 12 = division by 212

Note that the input images dimensions must be a multiple of 4 for the Geometry::DownSample to produce
the expected results.

Sync Memory Banks

The Sync Memory Banks example (SyncMemoryBanks.apf) shows how to use 2 (or more) RLD banks to form a single memory
bank with a larger bit width (that is, more pixels or higher parallelism). This technique can be useful in case a high bandwidth
branch needs to be buffered but the DDR memory banks has already been used elsewhere in the design.
The StreamControl::BranchCreate function creates two branches of the image stream
output of the Image I/O::CameraIn function. The PixelControl::KeepLSB and
PixelControl::KeepMSB functions extract the 4 least and 4 most significant bits which
are then buffered using Memory::FrameBuffer functions, using RLDRAM. With 4
pixels per clock at 8 bits each, a total of 32 bits per clock cycle is stored which is
optimal for the RLDRAM memory.
The StreamControl::BranchSync function synchronizes the two branches and the
PixelControl::PixelMerge reconstitutes the pixels.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 100

Sync Variable Latency

Note, the Sync Variable Latency example (SyncVariableLatencyOps.apf) is used to illustrate how resources can be wasted
unnecessarily by an inefficient design; a more efficient design that accomplishes the same task is shown in the Sync Variable
Latency Improved example.

Merging parallel branches with variable latencies requires that the flow control be well
understood in order to avoid deadlocks and inhibiting the input pixel stream. When
branches have variable latencies, the length of time required for each branch to
complete its operations is different and must be reconciled, or synchronized, so that the
pixels in both streams are simultaneous to each other.
Sapera APF provides warnings when variable latencies are used, but it is the users
responsibility to analyze these situations and ensure that proper buffering and
synchronization is in place to avoid errors.
In this example, 2 parallel paths each contain a Kernel::Convolution function which
has a variable-latency.
One branch uses a 5x5 kernel while the other uses a 3x3 kernel. The 5x5 kernel must
buffer more lines than the 3x3 kernel before processing the input image. Since the
kernel heights are different, pixels would arrive at the Math::Subtract at different
times. The StreamControl::BranchSync function is used to synchronize both streams,
forcing the faster 3x3 processing kernel stream to wait. The Memory::LineBuffer is
required on the faster branch to prevent the input stream from stopping; if flow control
signals that the faster branch must wait for the slower branch, the input pixel stream
would temporarily stop, creating a deadlock as both branches would be waiting for
data.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 101

Sync Variable Latency Improved

The Sync Variable Latency Improved example (SyncVariableLatencyOps_improved.apf) demonstrates a more efficient design
than that of the Sync Variable Latency.
Resource utilization is minimized by using the Kernel::KernelCreate before the
StreamControl::BranchCreate function, instead of using Kernel::KernelCreate functions
in each branch. The Kernel::KernelExtract function is used to create a 3x3 kernel from
the 5x5 kernel.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 102

Variable Output Dimensions

The Variable Output Dimensions example (VariableOutputDimensions.apf) uses the Boolean::LessThanVal function as the
control condition for the StreamControl::PixelRemoveCond; in this case, pixels with a value of less than 100 are deleted, which
results in frames where each line can have a different width.
The StreamControl::RectangleReshape formats the output to maintain rectangular images despite
variable line widths. In the example, RectangleReshapes parameters are configured to output
frames with dimensions 2048x1024, and the MaxFrameWidth and MaxFrameHeight of its output
link are set accordingly. The host application should allocate buffers with the same dimensions to
receive the data.

White Balance
The White Balance example (WhiteBalance.apf) uses the Color::WhiteBalance function to perform white balancing on the input
RGB image.

The StreamControl::Serialize function reduces the PixelsPerClock of the

input link from 8 to 2. This does not limit the maximum bandwidth since the
output Image::FrameOut2 uses the rgb24x2 format, therefore the maximum
number of pixels the PCIe bus can transfer per clock cycle is 2 RGB pixels.
In general, it is recommended that serializing, or reducing the pixels per
clock, be done as close to the source as possible to reduce FPGA resource
usage.
The Kernel::KernelCreate is used to create a 3x3 kernel to buffer the
incoming lines to be able to interpolate colors in the Bayer images mosaic.
The Color::BayerToRGB function performs the color conversion. Since the
output conversion has a bit width of 30, the PixelControl::KeepMSB
operates on each channel individually to convert the image back to 24 bits
per RGB pixel.
The Color::ChannelSplit is then used to separate the color channels to
different branches where a Math::SaturateHigh function limits the maximum
pixel value to 255. The Color::ChannelMerge is then used to merge these
channels back together into an RGB stream.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 103

YUV Processing
The YUV Processing example (YUVProcessing.apf) demonstrates how to change color formats from RGB to YUV to perform
processing on the luminance component of the resulting YUV image, and then return the image to RGB format for output to the
host.
The StreamControl::Serialize function reduces the PixelsPerClock of the input link from 8
to 2. This doesnt limit the maximum bandwidth since the output Image::FrameOut2 uses
the rgb24x2 format, therefore the maximum number of pixels the PCIe bus can transfer per
clock cycle is 2 RGB pixels. In general, it is recommended that serializing, or reducing the
pixels per clock, be done as close to the source as possible to reduce FPGA resource usage.
The Kernel::KernelCreate is used to create a 3x3 kernel to buffer the incoming lines to be
able to interpolate colors in the Bayer images mosaic.
The Color::BayerToRGB function performs the color conversion. Since the output
conversion has a bit width of 30, the PixelControl::KeepMSB operates on each channel
individually to convert the image back to 24 bits per RGB pixel.
The Color::RGBtoYUV function is used to convert the RGB input stream to YUV color
format. The Color::ChannelSplit then separates the YUV channels. The Math::ApplyLUT
applies a LUT to the luminance channel. The Color::ChannelMerge functions reassembles
the YUV image before using the Color::YUVtoRGB function to convert the image back
RGB format to send to the Image::FrameOut2 output.

Sapera APF Programmer's Manual

Sapera APF Introductory Exercises 104

Sapera APF Reference

The sections that follow provide a complete reference for the Sapera APF functions, organized in the following function libraries:

Boolean Functions

Color Functions

DataReduction

Directives Functions

Geometry Functions

Image I/O Functions

Kernel Functions

Math Functions

Memory Functions

PixelControl Functions

Signal I/O Functions

Statistics Functions

StreamControl Functions

Sapera APF Programmer's Manual

Sapera APF Reference 105

Boolean Functions
The Boolean functions can be used for pixel operations such as bitwise logic, thresholding, and other comparisons. These
functions operate either on individual bits (the Bitwise functions), or generate outputs with a single bit per pixel.

Boolean Function Library

BitwiseAnd

Performs bitwise AND operation on all inputs.

BitwiseNot

Performs bitwise NOT operation on all inputs.

BitwiseOr

Performs bitwise OR operation on all inputs.

BitwiseXnor

Performs bitwise XNOR operation on all inputs.

BitwiseXor

Performs bitwise XOR operation on all inputs.

Equal

Checks if the value at input link A is equal to the value at input link B.

EqualVal

Checks if the value at input link is equal to a specified value.

GreaterOrEqual

Checks if the value at input link A is greater or equal to the value at the input link B.

GreaterOrEqualVal

Checks if the value at input link is greater or equal to a specified value.

GreaterThan

Checks if the value at input link A is greater than the value at input link B.

GreaterThanVal

Checks if the value at input link is greater than a specified value.

InRange

Checks if the value at input link is inside a specified range of values.

LessOrEqual

Checks if the value at input link A is less than or equal to the value at the input link B.

LessOrEqualVal

Checks if the value at input link is less or equal to a specified value.

LessThan

Checks if the value at input link A is less or equal to the value at input link B.

LessThanVal

Checks if the input value at input link is less than a specified value.

NotEqual

Checks if the value at input link A is not equal to the value at input link B.

NotEqualVal

Checks if the value at input link is not equal to a specified value.

Sapera APF Programmer's Manual

Sapera APF Reference 106

Boolean::BitwiseAnd
Performs a bitwise AND operation on two or more inputs.

I/O Properties
Latency Type

Fixed

Inputs

In000 In063, input data

Outputs

Out, output data

Description
The BitwiseAnd function performs a bitwise logical AND operation. Each output bit is set to a logical "1" if the corresponding bits at the input links are "1",
otherwise the output is "0".
AND Truth Table
Input
A

Output

The number of input links can be modified at any time. To set the number of input links, select the input link and specify the required value in the Properties
dialog. If the number of input links is decreased, the removed input ports will be disconnected if they were connected.

Demo/Example Usage
ColorSegment

Sapera APF Programmer's Manual

Sapera APF Reference 107

Boolean::BitwiseNot
Performs a bitwise NOT operation on the input.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, output data

Description
The BitwiseNot function performs a bitwise logical inversion. Each output bit is set to a logical "1" if the corresponding bits at the input link is "0", otherwise
the output is "0".
NOT Truth Table
Input

Output

Demo/Example Usage
Multiple Outputs, Simple Processing

Boolean::BitwiseOr
Performs a bitwise OR operation on two or more inputs.

I/O Properties
Latency Type

Fixed

Inputs

In000 In063, input data

Outputs

Out, output data

Description
The BitwiseOr function sets the output to a logical "1" if any of the input values are "1", otherwise the output is "0".
OR Truth Table
Input

Output

1
1
1
The number of input links has to be selected at the creation of the modulecan be modified at any time. To set the number of input links, select the input link and
specify the required value in the Properties dialog. If the number of input links is decreased, the removed input ports will be disconnected if they were
connected.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 108

Boolean::BitwiseXNor
Performs a bitwise XNOR operation on two or more inputs.

I/O Properties
Fixed

Latency Type
Inputs

In000 In063, input data

Outputs

Out, output data

Description
The BitwiseXnor function performs a bitwise logical XNOR operation. Each output bit is set to a logical "1" if the number of corresponding bits at all input
links which are set to state "1" is even, otherwise the output is "0".
XNOR Truth Table
Input

Output

The number of input links has to be selected at the creation of the modulecan be modified at any time. To set the number of input links, select the input link and
specify the required value in the Properties dialog. If the number of input links is decreased, the removed input ports will be disconnected if they were
connected.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 109

Boolean::BitwiseXor
Performs a bitwise XOR operation on two or more inputs.

I/O Properties
Latency Type

Fixed

Inputs

In000In063, input data

Outputs

Out, output data

Description
The function BitwiseXor performs a bitwise logical XOR operation. Each output bit is set to a logical "1" if the number of corresponding bits at all input links
which are set to state "1" is odd, otherwise the output is "0".
XOR Truth Table
Input

Output

The number of input links has to be selected at the creation of the module and can be modified at any time. To set the number of input links, select the input link
and specify the required value in the Properties dialog. If the number of input links is decreased, the removed input ports will be disconnected if they were
connected.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 110

Boolean::Equal
Checks if the value at input link A is equal to the value at input link B.

I/O Properties
Latency Type
Inputs

Fixed
A, input data
B, input data

Outputs

Out, boolean (1 bit per pixel) output

Description
The Equal function outputs a logical "1" if the value at the input link A is the same as at input link B, otherwise the output is "0".

Demo/Example Usage
Not available

Boolean::EqualVal
Checks if the value at input link is equal to a specified value.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
Number

The data of the input link is tested against the value of this parameter.
Run-time
changeable

Yes

Default

Range

Valid range comprises the number space defined by the input link.

Description
The EqualVal function outputs a logical "1" if the value at the input link I is the same as the value of the parameter "Number", otherwise the output is "0".

Demo/Example Usage
Signal To Pixel

Sapera APF Programmer's Manual

Sapera APF Reference 111

Boolean::GreaterOrEqual
Checks if the value at input link A is greater or equal to the value at the input link B.

I/O Properties
Latency Type
Inputs

Fixed
A, input data
B, input data

Outputs

Out, boolean (1 bit per pixel) output

Description
The GreaterOrEqual function outputs a logical 1 if the value at input link A is greater or equal to the value at the input link B, otherwise the output is 0.

Demo/Example Usage
Auto-Threshold

Boolean::GreaterOrEqualVal
Checks if the value at input link is greater or equal to a specified value.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
Number

The data of the input link is tested against the value of this parameter.
Run-time
changeable

Yes

Default

Range

Valid range comprises the number space defined by the input link I.

Description
The GreaterOrEqualVal function outputs a logical "1" if the value at the input link is greater or equal to the value of the parameter Number, otherwise the output
is "0".

Demo/Example Usage
ColorSegment, ExtractKernel, Frame Diff, Median Pixel Replacement, Morph Close, Morph Dilate, Morph Erode, Multiple Outputs, Simple Threshold

Sapera APF Programmer's Manual

Sapera APF Reference 112

Boolean::GreaterThan
Checks if the value at input link A is greater than the value at input link B.

I/O Properties
Latency Type
Inputs

Fixed
A, input data
B, input data

Outputs

Out, boolean (1 bit per pixel) output

Description
The GreaterThanVal function outputs a logical "1" if the value at the input link A is greater than the value at the input link B, otherwise the output is "0".

Demo/Example Usage
Not available

Boolean::GreaterThanVal
Checks if the value at the input link is greater than a specified value.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
Number

The data of the input link is tested against the value of this parameter.
Run-time
changeable

Yes

Default

Range

Valid range comprises the number space defined by the input link.

Description
The GreaterThanVal function outputs a logical "1" if the value at the input link I is greater than the value of the parameter Number, otherwise the output is "0".

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 113

Boolean::InRange
Checks if the value at the input link is inside a specified range of values.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
From

To

The value at the input link is tested against the value of this parameter.
Run-time
changeable

No

Default

Range

Valid range comprises the number space defined by the input link.

The value at the input link is tested against the value of this parameter.
Run-time
changeable

No

Default

255

Range

Valid range comprises the number space defined by the input link.

Description
The InRange function outputs to a logical "1" if the value at the input link is equal to, or within, the interval defined by the parameters From and To (From <=
In<= To), otherwise the output is "0".

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 114

Boolean::LessOrEqual
Checks if the value at input link A is less than or equal to the value at input link B.

I/O Properties
Latency Type
Inputs

Fixed
A, input data
B, input data

Outputs

Out, boolean (1 bit per pixel) output

Description
The LessOrEqual function outputs a logical 1 if the value at the input link A is less than or equal to the value at the input link B, otherwise the output is 0.

Demo/Example Usage
Not available

Boolean::LessOrEqualVal
Checks if the value at the input link is less than or equal to a specified value.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
Number

The data of the input link is tested against the value of this parameter.
Run-time
changeable

Yes

Default

Range

Valid range comprises the number space defined by the input link.

Description
The LessThanVal function outputs a logical "1" if the value at the input link I is less or equal to the value of the parameter Number, otherwise the output is "0".

Demo/Example Usage
ColorSegment

Sapera APF Programmer's Manual

Sapera APF Reference 115

Boolean::LessThan
Checks if the value at input link A is less or equal to the value at input link B.

I/O Properties
Latency Type
Inputs

Fixed
A, input data
B, input data

Outputs

Out, boolean (1 bit per pixel) output

Description
The LessThan outputs a logical "1" if the value at the input link A is less or equal to the value at the input link B, otherwise the output is "0".

Demo/Example Usage
Not available

Boolean::LessThanVal
Checks if the input value at input link is less than a specified value.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
Number

The data of the input link is tested against the value of this parameter.
Run-time
changeable

Yes

Default

Range

Valid range comprises the number space defined by the input link I.

Description
The LessThan function outputs a logical "1" if the value at the input link is less than the value of the parameter Number, otherwise the output is "0".

Demo/Example Usage
Variable Output Dimensions

Sapera APF Programmer's Manual

Sapera APF Reference 116

Boolean::NotEqual
Checks if the value at input link A is not equal to the value at input link B.

I/O Properties
Latency Type
Inputs

Fixed
A, input data
B, input data

Outputs

Out, boolean (1 bit per pixel) output

Description
The NotEqual function outputs a logical "1" if the value at the input link A is not equal to the value at the input link B, otherwise the output is "0".

Demo/Example Usage
Not available

Boolean::NotEqualVal
Checks if the value at input link is not equal to a specified value.

I/O Properties
Latency Type

Fixed

Inputs

In, input data

Outputs

Out, boolean (1 bit per pixel) output

Parameters
Number

The data of the input link is tested against the value of this parameter.
Run-time
changeable

Yes

Default

Range

Valid range comprises the number space defined by the input link I.

Description
The NotEqualVal function outputs a logical "1" if the value at the input link is not equal to the value of the parameter Number, otherwise the output is "0".

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 117

Color Functions
The Color functions provide the functionality for processing color pixels.

Color Function Library

BayerToRGB

Generates an RGB image from a Bayer filtered image, using interpolation on a 3x3 kernel.

BayerToRGB_5X5

Generates an RGB image from a Bayer filtered image, using interpolation on a 5x5 kernel (uses algorithm from Malvar et al).

ChannelMerge

Merges three grayscale images into one color image.

ChannelSelect

Extracts a single color component from the input image.

ChannelSplit

Splits a color image into three separate grayscale images.

ColorMatrix_3x3

Implements a 3x3 matrix multiplication on input RGB values.

HSItoRGB

Converts the color space from HSI (Hue + Saturation + Intensity) to RGB (Red + Green + Blue).

RGBtoHSI

Converts the color space from RGB to HSI.

RGBtoYUV

Converts the color space from RGB to YUV (luminance Y + chrominance UV).

RGBtoYUV2

Converts the color space from RGB to YUYV (also known as YUV2)

WhiteBalance

Scales the three color components of an RGB input stream by three independent coefficients.

YUVtoRGB

Converts the color space from YUV to RGB.

Sapera APF Programmer's Manual

Sapera APF Reference 118

Color::BayerToRGB
Generates an RGB image from a Bayer filtered image, using interpolation on a 3x3 kernel.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Parameters
BayerInit

This parameter specifies the configuration of the bayer filter pattern, which is superimposed on the sensor.
Run-time
changeable

Yes

Default

GreenFollowedByRed

Options

Colors of the first 2 pixels:

GreenFollowedByRed

GreenFollowedByBlue

RedFollowedByGreen

BlueFollowedByGreen

Description
The Bayer function reconstructs a Bayer filtered image into an RGB image. A Bayer filtered raw image is technically a grayscale image which is composed
from alternating red, green and blue pixels. With Bayer it is possible to acquire a full RGB image from a bayer camera through a bi-linear reconstruction. The
input link should be a 3x3 kernel created from a bayer image using the Kernel::KernelCreate function.
Note that the output of this function can have a total bit width greater than the usual 24 bits expected for RGB. In this case, the PixelControl::KeepMSB
function can be used to adjust the total bit width to 24 bits (that is, 8 bits per color component).

Demo/Example Usage
Bayer, White Balance

Sapera APF Programmer's Manual

Sapera APF Reference 119

Color::BayerToRGB_5X5
Generates an RGB image from a Bayer filtered image, using interpolation on a 5x5 kernel (uses algorithm from Malvar et al).

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, RGB data output

Parameters
BayerInit

Specifies the configuration of the bayer filter pattern, which is superimposed on the sensor.
Run-time
changeable

Yes

Default

GreenFollowedByRed, dynamic

Options

Colors of the first 2 pixels:

GreenFollowedByRed

GreenFollowedByBlue

RedFollowedByGreen

BlueFollowedByGreen

Description
The BayertoRGB5x5 function reconstructs a Bayer filtered image into a RGB image using the high quality linear interpolation Malvar demosaic technique. A
Bayer filtered raw image is technically a grayscale image which is composed from alternating red, green and blue pixels. The input link should be a 5x5 kernel
created from a bayer image using the Kernel::KernelCreate function.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 120

Color::ChannelMerge
Merges three grayscale images into one color image.

I/O Properties
Latency Type

Fixed

Inputs

In0, data input (grayscale)

In1, data input (grayscale)
In2, data input (grayscale)

Outputs

Out, data output (color)

Description
Merges three grayscale input links into one color output link. The ColorType property of the output link should be set to identify the color space being used.

Demo/Example Usage
White Balance

Sapera APF Programmer's Manual

Sapera APF Reference 121

Color::ChannelSelect
Extracts a single color component from the input image.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (color)

Outputs

Out, data output (grayscale)

Parameters
Component

Defines the color component selected from the input

Run-time
changeable

No

Default

Range

0, 1, 2 (if the input is RGB, Component=0 selects red, 1 select green, and 2 selects blue)

Description
The ChannelSelect function extracts a single color component from the input link and makes this value available at the output link as a gray pixel.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 122

Color::ChannelSplit
Splits a color image into three separate grayscale images.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (color)

Outputs

Out0, data output (grayscale)

Out1, data output (grayscale)
Out2, data output (grayscale)

Description
The ChannelSplit function generates three separate gray image streams, each representing one single color component, from a color stream at the input link.

Demo/Example Usage
ColorSegment, White Balance

Sapera APF Programmer's Manual

Sapera APF Reference 123

Color::ColorMatrix3x3
Implements a 3x3 matrix multiplication on input color values.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (color)

Outputs

Out, data output (RGB)

Parameters
Resolution

Number of bits to encode digits after the radix point of the coefficients.
Run-time changeable No

Precision

Default

Range

1 30

Number of bits to encode the whole coefficient - resolution bits included.

Run-time changeable No

Coefficients

Default

16

Range

2- 31

The coefficient matrix, initialized with the identity transformation. All coefficients of the matrix are treated as signed numbers by the
function. The coefficients are double numbers.
Run-time changeable Yes, 9 entries
Default

Identity matrix (1 on main diagonal, 0 elsewhere)

Range

Depends on Precision and Resolution.

Description
The ColorMatrix3x3 function transforms the input color stream into a new color stream with weighted components. The transformation is performed by a 3x3
matrix multiplication on the input color values. The output color stream is unclipped and has the full bit resolution of the multiplication results. Depending on
the transformation algorithm, a further rounding and clipping might be necessary.
The transformation matrix is defined by the parameter Coefficients, a 3x3 matrix of double coefficients. The following forumula represents the transformation
algorithm.

All coefficients are treated as signed numbers. Therefore take care of the sign bit when defining Resolution and Precision parameters. The coefficients are
represented as double numbers. The function converts the coefficients to fixed point numbers and performs the entire arithmitic as such. The fixed point
attributes are defined by Resolution and Precision.
Note that the output of this function can have a total bit width greater than the 24 bits expected for RGB. In this case, the PixelControl::KeepMSB function can
be used to adjust the total bit width to 24 bits (that is, 8 bits per color component).
Precision defines the amount of bits used to encode the coefficients.
Resolution defines the amount of bits used to encode digits after the radix point.
Note that the output is always identified as being an RGB image. If the input image used a different color space, the outputs identified color space can be
modified using the Directives::ReinterpretColor function.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 124

Color::HSItoRGB
Converts the color space from HSI (Hue + Saturation+ Intensity) to RGB (Red + Green + Blue)
I/O Properties
Latency Type

Fixed

Inputs

In, data input. Total bit width supported: 24, 27, 30, 33, 36, 39, 42, 45, or 48.

Outputs

Out, data output

Parameters
HueAmplitude

Defines the maximum value for the hue. When input total bit width is 27 (that is, 9 bits per color component), using a maximum hue
amplitude of 360 gives a result in degrees
Run-time
changeable

No

Default

255

Range

Maximum value that can be represented at the input link.

Description
The HSItoRGB function converts the color space from HSI (Hue + Saturation + Intensity) to RGB (Red + Green + Blue).

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 125

Color::RGBtoHSI
Converts the color space from RGB (Red + Green + Blue) to HSI (Hue + Saturation + Intensity)

I/O Properties
Latency Type

Fixed

Inputs

In, data input. Total bit width supported: 24, 27, 30, 33, 36, 39, 42, 45, or 48

Outputs

Out, data output

Parameters
HueAmplitude

Defines the maximum value for the hue.

Run-time
changeable

No

Default

255

Range

Maximum value that can be represented at the input link.

Description
The function RGBtoHSI converts the color space from RGB (Red + Green + Blue) to HSI (Hue + Saturation + Intensity).
If the resulting HSI image needs to be sent to the host using the Image I/O::FrameOut functions, the Directives::ReinterpretColor function is required to
condition the output format for transmission purposes.

Demo/Example Usage
ColorSegment

Sapera APF Programmer's Manual

Sapera APF Reference 126

Color::RGBtoYUV
Converts the color space from RGB to YUV (luminance Y + chrominance UV).

I/O Properties
Latency Type

Variable

Inputs

In, data input. Total bit widths supported = 24.

Outputs

Out, data output

Description
The function RGBtoYUV converts the color space from RGB to YUV.
If the resulting YUV image needs to be sent to the host using the Image I/O::FrameOut functions, the Directives::ReinterpretColor function is required to
condition the output format for transmission purposes.

Demo/Example Usage
Not available

Color::RGBtoYUY2
Converts the color space from RGB to YUYV (also known as YUV2)

I/O Properties
Latency Type

Variable

Inputs

In, data input (rgb24x2)

Outputs

Y000, data output (gray8x1)

Y001, data output (gray8x1)
U, data output (gray8x1)
V, data output (gray8x1)

Description
The function RGBtoYUY2 converts the color space from RGB to YUYV (also known as YUY2). The 4 color components are output on separate links. The
YUYV pixels differ from the YUV pixels in that they contain only half of the chrominance information. One usage of the YUYV pixels is the color JPEG
compression.

Demo/Example Usage
JPEG RBG

Sapera APF Programmer's Manual

Sapera APF Reference 127

Color::WhiteBalance
Scales the three color components of an RGB input stream by three independent coefficients.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
ResolutionBits

RangeBits

RedCoefficient

GreenCoefficient

BlueCoefficient

Defines the precision for the fixed point multiplication. The entered floating point value is approximated to multiples of
1/2^ResolutionBits.
Run-time
changeable

No

Default

Range

1 16

Defines the valid range for the fixed point multiplication. The entered floating point value must meet the range [0, 2^RangeBits 1/2^ResolutionBits)].
Run-time
changeable

No

Default

Range

18

Defines the coefficient which scales the red component of the input. The entered floating point coefficient is rounded to the nearest
valid fixed point value (see RangeBits and ResolutionBits).
Run-time
changeable

Yes

Default

Range

Depends on RangeBits and ResolutionBits

Defines the coefficient which scales the green component of the input. The entered floating point coefficient is rounded to the nearest
valid fixed point value (see RangeBits and ResolutionBits).
Run-time
changeable

Yes

Default

Range

Depends on RangeBits and ResolutionBits

Defines the coefficient which scales the blue component of the input. The entered floating point coefficient is rounded to the nearest
valid fixed point value (see RangeBits and ResolutionBits).
Run-time
changeable

Yes

Default

Range

Depends on RangeBits and ResolutionBits

Description
The WhiteBalance function scales the three color components of an RGB input stream by three independent coefficients, which can be used for a manual white
balancing. The output values are rounded to meet the input bit width.
Note that the output of this function can have a total bit width greater than the 24 bits expected for RGB. In this case, the PixelControl::KeepMSB function can
be used to adjust the total bit width to 24 bits (that is, 8 bits per color component).

Sapera APF Programmer's Manual

Sapera APF Reference 128

Demo/Example Usage
White Balance

Color::YUVtoRGB
Converts the color space from YUV to RGB.

I/O Properties
Latency Type

Variable

Inputs

In, data input (yuv24x2)

Outputs

Out, data output (rgb24x2)

Description
The YUVtoRGB function converts the color space from YUV to RGB.

Demo/Example Usage
YUV Processing

Sapera APF Programmer's Manual

Sapera APF Reference 129

DataReduction Functions
The DataReduction functions provide the functionality for various forms of data reduction.

DataReduction Function Library

Huffman9bit4P

Perfoms Huffman encoding.

JPEGColor4P4k

Performs JPEG compression of color images up to 4096 pixels wide.

Paeth8bit4P8k

Applies a Paeth image prediction filter.

RLE8P

Performs run-length encoding

DataReduction::Huffman9bit4P
Performs Huffman encoding.

I/O Properties
Latency Type

Variable

Inputs

In, image gray9x4 (that is, gray-scale, 9 bits per pixel, 4 pixels per clock)

Outputs

Out, image

Description
Performs Huffman encoding on the input stream. For decoding, information on the Huffman table used is available upon request.

Demo/Example Usage
Lossless Compression

Sapera APF Programmer's Manual

Sapera APF Reference 130

DataReduction:: JPEGColor4P4k
Performs JPEG compression of color images up to 4096 pixels wide.

.
I/O Properties
Latency Type

Variable

Inputs

In, data input.

Outputs

Out, data output

Parameters
ImgWidth

ImgHeight

SizeX

SizeY

QtfAddr

QtfData

Width of the input images

Run-time
changeable

Yes

Default

Range

0-4096

Height of the input images

Run-time
changeable

Yes

Default

Range

0-4096

Width of the input images

Run-time
changeable

Yes

Default

Range

0-4096

Height of the input images

Run-time
changeable

Yes

Default

Range

0-4096

Used to update the JPEG quantization table.

Run-time
changeable

Yes

Default

Range

TBD

Used to update the JPEG quantization table.

Run-time

Sapera APF Programmer's Manual

Yes

Sapera APF Reference 131

changeable

QtfUpdateMono

QtfUpdateColor

HdrAddr

HdrData

Default

Range

TBD

Used to update the JPEG quantization table.

Type

Static parameter

Default

Range

TBD

Used to update the JPEG quantization table.

Run-time
changeable

Yes

Default

Range

TBD

Used to update the JPEG quantization table.

Run-time
changeable

Yes

Default

Range

TBD

Used to update the JPEG quantization table.

Run-time
changeable

Yes

Default

Range

TBD

Run-time
changeable

Yes

Default

Range

0-1

HdrUpdate

Description
Performs JPEG compression of the input image stream. The function assumes that the input image stream is gray8x4 (that is, grayscale, 8 bits per pixel, 4
pixels per clock) and represents a YUYV stream. The JPEGColor4P4k outputs a JPEG stream that must be formatted by the StreamControl::RectangleReshape
function so it can be transferred to the host. This JPEG stream includes the JPEG header and can be directly saved to disk with the .JPG extension.
ImgWidth, ImgHeight, SizeX and SizeY should be initialized to the dimensions of the input images, and all images should have the same dimensions. The
original RGB images should have a width equal or less than 4096 pixels.
In the JPEG algorithm, the quantization table can be modified to modulate the compression ratio. Information on how to modify the quantization table is
available upon request.

Demo/Example Usage
JPEG RBG

DataReduction::Paeth8bit4P8k
Applies a Paeth image prediction filter.

I/O Properties
Latency Type

Variable

Inputs

In, image gray8x4

Outputs

Out, image

Description
Applies a Paeth compression filter to the image.

Demo/Example Usage
Lossless Compression

DataReduction::RLE8P
Performs run-length encoding.
Sapera APF Programmer's Manual

Sapera APF Reference 132

I/O Properties
Latency Type

Variable

Inputs

In, image gray1x1, gray1x2, gray1x4, or gray1x8

Outputs

RLE, image gray18x1, gray19x2, gray20x4, gray21x4, or gray25x8.

Parameters
IFormat

IFormat

ImgWidth

ImgHeight

Defines the input format.

Run-time
changeable

No

Default

gray1x8

Range

gray1x8, gray2x8, gray3x8, gray4x8, gray8x8

Defines the RLE format.

Run-time
changeable

No

Default

255

Range

gray18x8, gray19x8, gray20x8, gray21x8, gray25x8

Width of the input images

Run-time
changeable

Yes

Default

Range

0-4096

Height of the input images

Run-time
changeable

Yes

Default

Range

0-4096

Description
Performs run-length encoding on input streams. Images must have a PixelsPerClock of 8. The I Format and RLE Format parameters should be chosen
according to the BitWidth of the input images:
Input
BitWidth

I Format

RLE Format

gray1x8

gray18x8

gray2x8

gray19x8

gray3x8

gray20x8

gray4x8

gray21x8

gray8x8

gray25x8

For each input line, the RLE output stream will contain one or more packets indicating the runs pixel value and their length, followed by 2 trailer packets
indicating the number of runs in the current line, and their vertical position Y.
The 1st (MSB) bit of the output packets is called trailer_bit and can be used to identify if a packet represents a RLE or a trailer:
When trailer_bit is 0, the packet format depends on the input format. Bit fields are listed from MSB to LSB:
gray1x8: trailer_bit(1 bit) | pixel_value (1 bit) | run_length(16 bits)
gray2x8: trailer_bit(1 bit) | pixel_value (2 bits) | run_length(16 bits)
gray3x8: trailer_bit(1 bit) | pixel_value (3 bits) | run_length(16 bits)
gray4x8: trailer_bit(1 bit) | pixel_value (4 bits) | run_length(16 bits)

Sapera APF Programmer's Manual

Sapera APF Reference 133

gray8x8:

trailer_bit(1 bit) | pixel_value (8 bits) | run_length(16 bits)

Each sequence of RLEs with trailer_bit equal to 0 is followed by 2 packets with trailer_bit equal to 1:
1st trailer : trailer_bit (1 bit) | num_runs_in_line (16 bits)
2nd trailer: trailer_bit (1 bit) | y_coord (16 bits)
The output packets can be repacked to 32-bits per pixel. Since the output stream is a single long line, the StreamControl::RectangleReshape function must be
used to transform it into an image that can be transferred to the host.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 134

Directives Functions
The Directives functions provide functions for changing the image color space, dimensions, and manipulating the input data
stream.

Directives Function Library

PixelBuffer

Outputs the registered input (no operation).

ReinterpretColor

Changes the image color space.

ReinterpretMaxDimensions

Changes the maximum image dimension.

ReinterpretPixelsPerClock

Enables the re-interpretation of the bits of the input link.

ReinterpretSign

Changes the sign of the input data.

Directives::PixelBuffer
Used to ease FPGA place-and-route.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The PixelBuffer function has no influence on the image processing algorithm in the Sapera APF design. Image data is not changed. The PixelBuffer function
will briefly store the input pixels in the FPGAs internal memory. This can be used to cut a critical propagation path in the FPGA which would otherwise
prevent the design from meeting timing constraints at a given FPGA clock frequency. Inserting a PixelBuffer function gives the place-and-route tools more
flexibility on where functions can be positioned inside the FPGA. There are multiple situations where a PixelBuffer function can be helpful:
When images are stored to external memory (for example, using the Memory::FrameBuffer function), the place-and-route tool must position some
internal functions near the FPGAs external pins. This can lead to failed timing; in this case, PixelBuffer functions can be inserted before and after the
FrameBuffer function.
When there are long sequences of fixed-latency functions, it may help to insert a PixelBuffer function in the middle.
In general, whenever a designs place-and-route fails because of timing issues, one or more copies of the PixelBuffer function can be inserted, and place-androute re-attempted.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 135

Directives::ReinterpretColor
Allows color images to be interpreted as that of another format.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The ReinterpretColor function allows various image color spaces to be interpreted as another format for validation and transmission purposes. That is, the actual
data is not changed, but the color channels are interpreted as if in another format. Since the Image I/O::FrameOut functions only support the rgb24x2 color
format, this function can be used to output other color formats, such as HIS, YUV, LAB, and XYZ, .as if they were RGB.
To specify the output color, select the output link and use the Property field Color type.

Demo/Example Usage
Not available

Directives::ReinterpretMaxDimension
Changes the maximum image dimensions.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The ReinterpretMaxDimension function makes it possible to change the values of the maximum image dimension. Usually this information is set at the camera
ports and remains unchanged. However, if your algorithm crops the image it might be necessary to return to the original image dimensions, by editing
MaxFrameWidth and MaxFrameHeight parameters at the output link.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 136

Directives::ReinterpretPixelsPerClock
Enables the re-interpretation of the bits of the input link.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The ReinterpretPixelsPerClock function enables the re-interpretation of the bits of the input link. For example, an input link with 16 bits/pixel and a
PixelsPerClock of two transmits 32 bits at each clock cycle. The ReinterpretPixelsPerClock function gives you the possibility to interpret these 32 bits as 8
bits/pixel at PixelsPerClock 4, or 4 bits/pixel at PixelsPerClock 8, and so forth. Therefore, the constraint is, that the value of (Width* PixelsPerClock ) is
identical for the input and the output link. The 2nd constraint is that the output pixel width must not exceed 64 bits.
To specify the PixelsPerClock, select the output link and set the PixelsPerClock parameter.

Demo/Example Usage
Lossless Compression

Directives::ReinterpretSign
Changes the sign of the input data.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The function ReinterpretSign changes the sign of the input data to signed or unsigned. The bits of the input values remain unchanged.
To specify the sign, select the output link and set the Arithmetic parameter.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 137

Geometry Functions
The Geometry functions provide the functionality for changing the image size.

Geometry Function Library

DownSample

Reduces the image size by down sampling the input image.

UpSample

Increases the image size by up sampling the input image.

Geometry::DownSample
Reduces the image size by down sampling the input image.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
XSampleDown

YSampleDown

Selects the down sampling ratio for the image width.

Run-time
changeable

No

Default

Range

1 - 128

Selects the down sampling ratio for the image height.

Run-time
changeable

No

Default

Range

1 - 128

Description
The DownSample function reduces the image size by down-sampling the input image. The down-sampling can be performed independently in width and height
by any positive integer number up to 128. The output pixels are computed by averaging the joined pixels. The output image width will be reduced to (input
image width) / XSampleDown. The output image height is reduced to (input image height) / YSampleDown.
The DownSample function works properly only on rectangular images,that is, images whose lines are of equal length. Images with variable line length in the
same image will lead to wrong results. The StreamControl::RectangleReshape function can be used to make sure input images are properly formatted for the
DownSample function.
When the down-sampling parameters are set to a value that exceeds the width/height of the input image, the resulting image will be an empty image.
When the image width/height is not divisible by the correspondent sampling down parameter value, the function will cut off the borders with incomplete pixel
sets.

Demo/Example Usage
Subsampled Processing

Sapera APF Programmer's Manual

Sapera APF Reference 138

Geometry::UpSample
Increases the image size by upsampling the input image.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
XSampleUp

YSampleUp

Selects the upsampling ratio for the image width.

Run-time
changeable

No

Default

UpSampleXBy2

Range

UpSampleXBy1, UpSampleXBy2, UpSampleXBy4, UpSampleXBy8, UpSampleXBy16

Selects the upsampling ratio for the image height.

Run-time
changeable

No

Default

Range

UpSampleYBy1, UpSampleYBy2, UpSampleYBy4, UpSampleYBy8, UpSampleYBy16

Description
The UpSample function increases the image size by up-sampling the input image. The up-sampling can be performed independently in width and height by
steps of 1, 2, 4, 8, and 16. The output pixels are computed by duplicating pixels (nearest neighbor).

Demo/Example Usage
Subsampled Processing

Sapera APF Programmer's Manual

Sapera APF Reference 139

Image I/O Functions

The Image I/O functions provide the functionality for configuring the image inputs and outputs of the Sapera APF design.

Image I/O Function Library

CameraIn

Receives the image stream from the FPGAs front end.

FrameCreateBlank

Generates an emptyimage with the specified dimensions.

FrameOutRaw
FrameOut2
FrameOut3
FrameOut4

Transfers images to the host computers memory.

RecursiveIn

Used to receive previously computed intermediate results that have been sent to the RecursiveOut function.

RecursiveOut

Outputs intermediate results to the RecursiveIn function.

Image I/O::CameraIn
Receives the image stream from the FPGAs front end.

I/O Properties
Latency Type

Variable

Outputs

Out, image data output

Parameters
MaxFrameHeight

MaxFrameWidth

LinkFormat

Defines the maximum image height (y) in lines.

Run-time
changeable

No

Default

Determined by front-end selection

Range

1 to 65536

Defines the maximum image width (x) in pixels.

Run-time
changeable

No

Default

Determined by front-end selection

Range

4 to 65536

Defines the pixel format at the output link

Run-time
changeable

Sapera APF Programmer's Manual

No

Sapera APF Reference 140

CC1Ctrl, CC1Ctr2,
CC1Ctr3, CC1Ctr4,

Default

Determined by front-end selection

Range

gray8x8: grayscale, 8-bits per pixel x 8 pixels per clock

gray16x4; grayscale, 16-bits per pixel x 4 pixels per clockrgb24x2, color, 24-bits per rgb pixel x 2 pixels
per clock

Determines how the related CC camera control signal is driven

Run-time
changeable

Yes

Default

Range

0: the CC signal will be driven the front-end, based on standard Sapera LT parameters
1: the CC signal will be driven by the related GPO function
2: the CC signal will be driven to a constant 0
3: the CC signal will be driven to a constant 1

Description
The CameraIn function reads the image stream from the FPGAs front end and makes it available at its output link to the processing functions. When a frontend is selected for a design (either by loading a .ccf camera configuration file, or directly selecting the front-end), the CameraIn function is automatically added
to the program. The output of the CameraIn function is always 64-bits per clock cycle, except for the rgb24x2 format which has 48-bits per clock cycle.
A firmware generated by Sapera APF can support a range of cameras or camera modes, as long as the pixel format remains the same and the tap configuration is
compatible. If multiple camera image dimensions are to be supported, then MaxFrameWidth and MaxFrameHeight should be set to the largest dimensions.
Sapera APF will allocate enough FPGA resources to allow processing of images with dimensions up to those defined by MaxFrameWidth and
MaxFrameHeight. Those maximum dimensions will typically propagate throughout the design, so it is advisable to keep these values to the minimum required
dimensions to avoid using FPGA resources unnecessarily.

Demo/Example Usage
All examples

Sapera APF Programmer's Manual

Sapera APF Reference 141

Image I/O::FrameCreateBlank
Generates an empty image with the specified dimensions.

I/O Properties
Latency Type

Variable

Outputs

Out, image data output

Parameters
ImageWidth

ImageHeight

Defines the image width (x) in pixels.

Run-time
changeable

Yes

Default

1024

Range

Up to MaxFrameWidth of the output link

Defines the image height (y) in lines.

Run-time
changeable

Yes

Default

1024

Range

1 to MaxFrameHeight of the output link

Description
The FrameCreateBlank function generates an emptyimage of the specified height and width. This image can be expanded by other functions. For example, it
can be modified by other functions, then passed to a StreamControl::BranchSync function in order to be combined with incoming images from the camera.
The MaxFrameWidth, MaxFrameHeight and PixelPerClock properties of the output link can be modified:

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 142

Image I/O::FrameOutRaw, FrameOut2, FrameOut3, FrameOut4

Transfers images to the host computers memory.

I/O Properties
Latency Type

Variable

Inputs

In, image data

Parameters
LinkFormat

Disable

TimestampInStream

Defines the image pixel format expected at the input link

Run-time
changeable

No

Default

Determined by front-end selection

Range

gray8x8: grayscale, 8-bits per pixel x 8 pixels per clock

gray16x4: grayscale, 16-bits per pixel x 4 pixels per clock
rgb24x2: color, 24-bits per rgb pixel x 2 pixels per clock

Used internally by the frame grabber driver.

Run-time
changeable

Yes

Default

0 (False)

Range

0 (False), 1 (True)

Reserved for future use

Run-time
changeable

InitialDelNumFrames

PeriodicSendNumFrames

Default

0 (False)

Range

0 (False), 1 (True)

See the Timestamp section below.

Run-time
changeable

Yes

Default

Determined by front-end selection

Range

0 to 255

See the Timestamp section below.

Run-time
changeable

PeriodicDelNumFrames

Yes

Yes

Default

Determined by front-end selection

Range

0 to 255

See the Timestamp section below.

Run-time
changeable

Yes

Default

Determined by front-end selection

Range

0 to 255

Description
Transfers images to the host computers memory. Images output by FrameOutRaw can be used by applications that have no explicit support for image
processing (for example, Saperas CamExpert tool). The designer must make sure that the frames output using the FrameOutRaw function have the same

Sapera APF Programmer's Manual

Sapera APF Reference 143

dimensions and pixel format as those received by the Image I/O::CameraIn function.
The FrameOut2, FrameOut3, and FrameOut4 functions can accept images of different formats and of different size than the input image.
If necessary, the Directives::ReinterpretColor function can be used to allow the transmission of different color formats over a rgb24x2 output link.
Timestamps
Teledyne DALSA frame grabbers associate a timestamp to every image acquired from cameras. This very precise timestamp is taken in the front-end and does
not vary with random system events like CPU load, PCIe latencies, and so forth.

For firmwares generated with Sapera APF, a special approach is taken. Since there is currently no support for receiving these timestamps in Sapera APF; the
timestamps are forwarded around the APF processing section, where they are associated back with their frame by the Image I/O::FrameOut functions:

This approach works well for the typical one frame in, one frame out scenario. Other scenarios like one frame in, N frames out or N frames in, one frame
out are supported by modifying the timestamp parameters:
InitialDelNumFrames

Used when the processing removes the N 1st frames after acquisition has started. In this
case, InitialDelNumFrames can be set to N so that the timestamps of the removed
frames are removed as well.

PeriodicSendNumFrames

Sets the number of frames sent for each frame at the input. For example, if every frame
at the input of the processing results in 10 frames at the output, this parameter would be
set to 10, since for every timestamp at the input 10 frames are produced. In this case, all
10 output frames will have the same timestamp. For the typical one frame in, one frame
out scenario, PeriodicSendNumFrames should be 1.

PeriodicDelNumFrames

Sets the number of frames deleted (trashed or not sent) between the input and output. For
example, if every 10 frames at the input of the processing results in only 1 frame at the
output, this parameter would be set to 10, to make sure that the associated timestamps
are also removed.

Demo/Example Usage
All examples

Sapera APF Programmer's Manual

Sapera APF Reference 144

Image I/O::RecursiveIn
Receives previously computed intermediate results that have been sent to the RecursiveOut function.

I/O Properties
Latency Type

Variable

Outputs

Out, data output

Parameters
MaxFrameHeight,
MaxFrameWidth

Link Format

Defines the maximum image width (x) and height (y) in pixels.
Run-time
changeable

No

Default

1024

Range

any

Defines the expected image format at the input link.

Run-time
changeable

No

Default

gray8x8x1

Options

DataType = Line:
gray8x8x1, gray16x4x1, rgb24x2x1
DataType = Image:
gray8x8x2, gray16x4x2, rgb24x2x2

Description
Receive previously computed intermediate results that have been sent to the Image I/O::RecursiveOut function. That is, the input to the RecursiveIn function is
the output of the RecursiveOut function. The RecursiveIn and RecursiveOut functions can be used to bypass the design connection rules that prevent having a
feedback loop within the design.

Demo/Example Usage
Recursive Average

Sapera APF Programmer's Manual

Sapera APF Reference 145

Image I/O::RecursiveOut
Used to output intermediate results to be used as an input when processing the next image.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Parameters
Link format

Defines the output image format expected at the input link.

Run-time
changeable

No

Default

Gray8x8x1

Range

DataType = Line:
gray8x8x1, gray16x4x1, rgb24x2x1
DataType = Image:
gray8x8x2, gray16x4x2, rgb24x2x2

Description
Used to output intermediate results to be used as an input when processing the next image. The image is sent to the Image I/O::RecursiveIn function.

Demo/Example Usage
Recursive Average

Sapera APF Programmer's Manual

Sapera APF Reference 146

Kernel Functions
The Kernel functions provide the functionality for implementing various neighborhood operations.

Kernel Function Library

BinaryDilate

Performs a binary dilation of the image, which can be used to bridge gaps of zeros in the image.

BinaryErode

Performs a binary erosion of the image, which can be used to separate touching objects.

Convolution

Performs a convolution between the input image and a convolution kernel.

GrayscaleDilate

Identifies and outputs the maximum of an input kernel-stream.

GrayscaleErode

Identifies and outputs the minimum of an input kernel-stream.

HitOrMiss

Implements the morphological image function "Hit or Miss" as matching with define structure.

KernelCreate

Creates rectangular kernel window around each pixel, which includes the neighbor pixels.

KernelExtract

Extracts a rectangular subset of the kernel matrix at the input link.

KernelSplit

Splits the N x M kernel components of the input link into j = N * M output links.

Median

Identifies and outputs the median of an input kernel-stream. The kernel size is limited to 3x3 and 5x5.

Sapera APF Programmer's Manual

Sapera APF Reference 147

Kernel::BinaryDilate
Performs a binary dilation of the image.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

Out, image data output

Parameters
StructElement

Defines the shape of the structuring element. A '1' includes a particular pixel position of the kernel into the dilate operation and a 0
indicate the pixel position is not considered (or dont care). Click Press to open the kernel structuring element dialog.
Run-time
changeable

No

Default

Range

0, 1

Description
The BinaryDilate function performs a binary dilation of the image, which can be used to bridge gaps of zeros in the image. That is, the basic effect of the
function is to gradually enlarge the boundaries of regions of foreground pixels (white pixels). Thus areas of foreground pixels grow in size while holes within
those regions become smaller.
The input is a kernel-stream (see Kernel::KernelCreate) and the output link gives the calculated value for the center pixel.
A structuring element for the dilate operation is given by a user modifiable binary matrix. The matrix has the size of the input kernel. The output is set to '1', if
any matrix and kernel element is not '0' at the same time. That is, for each background pixel (the input pixel) if at least one pixel in the structuring element
coincides with a foreground pixel in the image underneath, then the input pixel is set to the foreground value. If all the corresponding pixels in the image are
background, however, the input pixel is left at the background value.

Demo/Example Usage
ExtractKernel, Morph Close, Morph Dilate, Morph Open

Sapera APF Programmer's Manual

Sapera APF Reference 148

Kernel::BinaryErode
Performs a binary erosion of the image.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

Out, image data output

Parameters
StructElement

Defines the shape of the structuring element. A '1' includes a particular pixel position of the kernel into the erode operation and a 0
indicate the pixel position is not considered (or dont care). Click Press to open the kernel structuring element dialog.
Run-time
changeable

No

Default

Range

0, 1

Description
The function BinaryErode performs a binary erosion of the image, which can be used to separate touching objects. The input is a kernel-stream (see
Kernel::KernelCreate) and the output link gives the calculated value for the center pixel.
A structuring element for the erode operation is given by user modifiable binary matrix. The matrix has the size of the input kernel. The output is set to '1', if all
matrix elements of '1' have corresponding kernel elements of '1'. That is, for each foreground pixel (the input pixel) if at least one pixel in the structuring
element coincides with a background pixel in the image underneath, then the input pixel is set to the background value. If all the corresponding pixels in the
image are foreground, however, the input pixel is left at the foreground value.

Demo/Example Usage
Morph Close, Morph Erode, Morph Open

Sapera APF Programmer's Manual

Sapera APF Reference 149

Kernel::Convolution
Performs a convolution between the input image and a convolution kernel.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

Out, image data output

Parameters
Coefficients

Defines the coefficients of the filter kernel. Click Press to open the kernel structuring element dialog.
Run-time
changeable

No

Default

000
010
000

Range

-65536 to 65535

Description
Performs a convolution between the input image and a convolution kernel (set at design-time). The input is a kernel-stream (see Kernel::KernelCreate) and the
output link gives the calculated value for the center pixel.
A structuring element for the convolution operation is given by user modifiable matrix. The matrix has the size of the input kernel

Demo/Example Usage
Gaussian5x5, Median Pixel Replacement, Sobel Edge, Sync Variable Latency, Sync Variable Latency Improved

Kernel::GrayscaleDilate
Identifies and outputs the maximum of an input kernel-stream.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

Out, image data output

Description
The GrayscaleDilate function identifies and outputs the maximum of an input kernel-stream. That is, the highest grayscale value in the specified neighborhood
matrix around the center pixel is output as its value.
The input is a kernel-stream and the output link gives the calculated value for the center pixel. An input kernel stream is created using the Kernel::KernelCreate
function.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 150

Kernel::GrayscaleErode
Identifies and outputs the minimum of an input kernel-stream.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input

Outputs

Out, image data output

Description
The GrayscaleDilate function identifies and outputs the minimum of an input kernel-stream. That is, the lowest grayscale value in the specified neighborhood
matrix around the center pixel is output as its value.
The input is a kernel-stream and the output link gives the calculated value for the center pixel. An input kernel stream is created using the Kernel::KernelCreate
function.

Demo/Example Usage
Not available

Kernel::HitOrMiss
Implements the morphological image function "Hit or Miss".

I/O Properties
Latency Type

Fixed

Inputs

In, binary kernel image data input

Outputs

Out, image data output

Parameters
StructElement

Defines the shape of the structuring element. A '1' and '0' needs the search pattern to match, a -1 acts as 'don't care'. Click Press
to open the kernel structuring element dialog.
No
Run-time
changeable
Default

Range

-1, 0, 1

Description
The HitOrMiss function performs a morphological Hit or Miss operation of the binary image, which can be used to identify structures or objects. The input is a
kernel-stream (see Kernel::KernelCreate) and the output link gives the calculated value for the center pixel. A structuring element for the Hit or Miss operation
is given by a user modifiable matrix. The matrix has the size of the input kernel.
The output is set to '1' for a pixel if the kernel neighbourhood of the pixel exactly matches with the pattern defined in the matrix defined by the parameter
StructElement, 'and 0' if there are differences. The search pattern defined in StructElement can be either 0 or 1 requiring the pixel neighbourhood to match with
this pattern, or -1 as a dont care for ignored parts in the structuring element.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 151

Kernel::KernelCreate
Buffers the required neighboring pixels around each matrix to send as a kernel stream at the output.

I/O Properties
Latency Type

Variable

Inputs

In, image data input

Outputs

Out, kernel data output

Parameters
EdgeHandling

Defines what values are used in the output kernels when the corresponding input pixels are outside the boundaries of the input image.
Run-time
changeable

No

Default

EdgeMirrored.

Options

EdgeMirrored: Use mirrored pixels, if the kernel exceeds the image.

EdgeConstant: Fill the kernel with constant pixels, if the kernel exceeds the image. The value for these pixels can
be selected by the parameter Constant

Constant

Defines the pixel value when the kernel exceeds the image and the parameter EdgeHandling is set to EdgeConstant.
Run-time
changeable

No

Default

Range

Depends on output bit width.

Description
The KernelCreate function buffers the required neighboring pixels around each matrix to send as a kernel stream at the output. The size of the kernel and the
border handling algorithm is selectable.
To set the size of the kernel, select the output link and use the KernelHeight and KernelWidth parameters.

Note that the bandwidth required increases with the size of the kernel. For example, a 5x5 kernel requires the transfer of 25 pixels for each PixelPerClock.
For even matrices, the center pixel is displaced to the upper left corner, for example 4x4 defines the center pixel at (2,2).

Sapera APF Programmer's Manual

Sapera APF Reference 152

Refer to the Using Kernels section for more information on using kernels.

Demo/Example Usage
Bayer, ColorSegment, ExtractKernel, , Gaussian5x5, Median Filter, Median Pixel Replacement, Morph Close, Sobel Edge, Sync Variable Latency, Sync
Variable Latency Improved

Kernel::KernelExtract
Extracts a rectangular subset of a kernel.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

Out, kernel data output

Parameters
FirstROW

FirstCOL

Defines the first row for the new kernel.

Run-time
changeable

No

Default

Range

Depends on the kernel size of the input

Defines the first column for the new kernel.

Run-time
changeable

No

Default

Range

Depends on output bit width.

Description
The KernelExtract function extracts a rectangular subset of the kernel matrix at the input link. Similar to an ROI, an offset for the first element of the new kernel
is selectable using the FirstROW and FirstCOL parameters, the size (width/height) of the new kernel can be chosen at the output link.
To set the size of the kernel, select the output link and set the KernelHeight and KernelWidth parameters.

Demo/Example Usage
ExtractKernel, Median Pixel Replacement, Sync Variable Latency Improved

Sapera APF Programmer's Manual

Sapera APF Reference 153

Kernel::KernelSplit
Splits the N x M kernel components of the input link into j = N * M output links.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

O0O(j-1) data output

Description
The KernelSplit function splits the N x M kernel components of the input link into j = N * M output links. The amount of output links j has to be specified on
function initialization. The amount of links has to be equal to the number of kernel components.
To set the number of output links, select the Output node and specify the required value in the Properties dialog.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 154

Kernel::Median
Identifies and outputs the median of an input kernel-stream.

I/O Properties
Latency Type

Fixed

Inputs

In, kernel image data input

Outputs

Out, center pixel output

Description
The Median function identifies and outputs the median of an input kernel-stream (see Kernel::KernelCreate).
A median filter considers each pixel in the image in turn and looks at its nearby neighbors to replace it with the median of those values. The median is
calculated by first sorting all the pixel values from the surrounding neighborhood into numerical order and then replacing the pixel being considered with the
middle pixel value. (If the neighborhood under consideration contains an even number of pixels, the average of the two middle pixel values is used.)
The median is a more robust average than the mean and so a single very unrepresentative pixel in a neighborhood will not affect the median value significantly.
Since the median value must actually be the value of one of the pixels in the neighborhood, the median filter does not create new unrealistic pixel values when
the filter straddles an edge. For this reason the median filter is much better at preserving sharp edges than the mean filter.
The kernel size is limited to 3x3 and 5x5.

Demo/Example Usage
Median Filter, Median Pixel Replacement, Multiple Outputs

Sapera APF Programmer's Manual

Sapera APF Reference 155

Math Functions
The Math functions provide the functionality for performing arithmetic, saturation, LUT and bit shift operations, on grayscale
pixel values.

Math Function Library

AbsoluteValue

Calculates the absolute value of the input.

Add

Calculates the sum over multiple input links.

ApplyLUT

Applies a configurable LUT to input gray-scale pixels.

Constant

Replaces the input pixels by a constant value.

Divide

Divides the input link 1 by the input link 2.

Multiply

Multiplies the input link 1 by the input link 2

MultiplyByVal

Multiplies the input link by a constant

SaturateHigh

Limits the values to a user-specified maximum.

SaturateLow

Limits the values to a user-specified minimum.

ShiftLeft

Performs an arithmetic shift of the input data to the left.

ShiftRight

Performs an arithmetic shift of the input data to the right.

Subtract

Calculates the difference of the two input links.

Math::AbsoluteValue
Calculates the absolute value of the input.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Description
The AbsoluteValue function calculates the absolute value of the input, for example, Out = In, if In >= 0 and Out = -In, if In < 0. The input must be signed.
The Directives::ReinterpretSign function can be used to change the sign of a link without changing the actual bits.

Demo/Example Usage
Frame Diff, Median Pixel Replacement, Sobel Edge

Sapera APF Programmer's Manual

Sapera APF Reference 156

Math::Add
Calculates the sum over multiple input links.

I/O Properties
Latency Type

Fixed

Inputs

In0In63, data input

Outputs

Out, data output

Description
The function Add calculates the sum over multiple input links. Links must have the same I/O Properties. The number of input links has to be selected at the
creation of the module.
To set the number of input links, select the Input node and specify the required value in the Properties dialog.

Demo/Example Usage
Recursive Average

Math::ApplyLUT
Applies a configurable LUT to input gray-scale pixels.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Parameters
LUTContent

Defines the coefficients of the LUT. Click Press to open the LUT dialog.
Run-time
changeable

Yes

Default

256-bins LUT with incrementing values

Range

Depends on bit width of the output link, which can be changed by clicking on the output link and editing the
BitWidth property.

Description
The ApplyLUT function implements a look-up-table . The default content of the LUT is defined by setting the parameter LUTContent.

Demo/Example Usage
Flat Line Correction

Sapera APF Programmer's Manual

Sapera APF Reference 157

Math::Constant
Replaces the input pixels by a constant value.

I/O Properties
Latency Type

Fixed

Inputs

In, image with desired image dimensions

Outputs

Out, constant data output

Parameters
Value

Defines the value available at the output link.

Run-time
changeable

Yes

Default

Range

Depends on sign and bit width of the output link

Description
The Constant function provides a fixed value at the output link. It needs an input link just to define the shape of the image for the output link.
Note that for multi-component formats like RGB, the constant value is defined as a single value for the pixel not the component. For example, with an RGB 8bit
input link, and the constant value set to 11862494 (0xB501DE), the output components will be set to the following const values: R = 222 (0xDE), G = 01 (0x01)
and B = 181 (0xB5).
The constant concatenates the component values to a single value. The component 0 is placed in LSB area and the highest component in MSB area, for
example, for RGB the constant value is {B-G-R}. Value = {component N-1, ..., component 0}, with N being the number of the components.

Demo/Example Usage
Auto Gain, Auto-Threshold

Sapera APF Programmer's Manual

Sapera APF Reference 158

Math::Divide
Divides the input link 1 by the input link 2.

I/O Properties
Latency Type

Fixed

Inputs

In1, data input of the dividend (or numerator)

In2, data input of the divisor (or denominator)

Outputs

Out, data output of the integer result

R, data output of the remainder

Description
The function divides the input link In1 by the input link In2. The output link Out is the integer result of this division and the output R represents the remainder.
A division by zero results in the maximum possible value representable at output link Out, that is, all bits set. In this case, the remainder is equal to the input
value at In1.

Demo/Example Usage
Auto Gain, Gaussian5x5

Math::Multiply
Multiplies the input link 1 by the input link 2.

I/O Properties
Latency Type

Variable

Inputs

In1, data input (1 to 32 bits)

In2, data input (1 to 32 bits)

Outputs

Out, data output of I1*I2 (1 to 32 bits)

Description
This function multiplies the input link In1 by the input link In2 and the result In1*In2 is available at the output link.

Demo/Example Usage
Auto Gain

Sapera APF Programmer's Manual

Sapera APF Reference 159

Math::MultiplyByVal
Performs a multiplication of the input by a constant.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (1 to 32 bits)

Outputs

Out, data output (1 to 32 bits)

Parameters
ScaleFactor

ScaleFactorMaxBits

Defines the constant factor for the multiplication.

Run-time
changeable

Yes

Default

Range

Maximum value that can be represented at the input link.

Defines the bit width for the constant.

Run-time
changeable

No

Default

Range

1 to 32

Description
The MultiplyByVal function performs a multiplication of the input by a constant, specified by the ScaleFactor parameter.

Demo/Example Usage
Auto Gain, Auto-Threshold, ColorSegment, Flat Line Correction, Frame Diff, Morph Close, Simple Processing, Sobel Edge, Subsampled Processing

Sapera APF Programmer's Manual

Sapera APF Reference 160

Math::SaturateHigh
Limits values to a specified maximum value.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (1 to 64 bits)

Outputs

Out, data output (1 to 64 bits)

Parameters
to

Defines the maximum value for the output link.

Run-time
changeable

No

Default

128

Range

Maximum value that can be represented at the input link.

Description
The SaturateHigh function limits the values to a specified maximum. If the input exceeds the maximum it is clipped, for example,. Out = In, if In < max and Out
= max, if In >= max.

Demo/Example Usage
Auto Gain, Gaussian5x5, White Balance

Sapera APF Programmer's Manual

Sapera APF Reference 161

Math::SaturateLow
Limits values to a specified minimum value.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Parameters
from

Defines the minimum value for the output link.

Run-time
changeable

No

Default

Range

Minimum value that can be represented at the input link.

Description
The SaturateLow function limits the values to a specified minimum. If the input falls below the minimum it is clipped, for example. Out = In , if In > min and
Out = min, if In <=min.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 162

Math::ShiftLeft
Performs an arithmetic shift of the input data to the left.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Parameters
Shift

Defines the number of bits by which the input is shifted left.

Run-time
changeable

No

Default

Range

1 to 64

Description
The ShiftLeft function performs an arithmetic shift of the input data to the left. The number of bits to be shifted can range from 1 to 64, depending on the input
bit width. Shifting left by n bits on a signed or unsigned binary number has the effect of multiplying it by 2n.
For example, an 8-bit width input shifted to the left by one replaces the least-signficant bit with a zero, while discarding the most significant bit.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 163

Math::ShiftRight
Performs an arithmetic shift of the input data to the right.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (1 to 64 bits)

Outputs

Out, data output (1 to 64 bits)

Parameters
Shift

Defines the number of bits by which the input is shifted right.

Run-time
changeable

No

Default

Range

1 to 64

Description
The ShiftRight function performs an arithmetic shift of the input data to the right. The number of bits to be shifted can range from 1 to 64, depending on the
input bit width. Shifting right by n bits on a signed or unsigned binary number has the effect of dividing it by 2n.
For example, an 8-bit width input shifted to the right by one copies the most-signficant bit (this preserves the sign-bit for signed values), while discarding the
least significant bit.

Demo/Example Usage
Auto Gain, Gaussian5x5, Subsampled Processing

Sapera APF Programmer's Manual

Sapera APF Reference 164

Math::Subtract
Calculates the difference of the two input links.

I/O Properties
Latency Type

Fixed

Inputs

In1, data input to subtract from (1 to 64 bits)

In2, data input to subtract by (1 to 64 bits)

Outputs

Out, data output difference

Description
The Subtract function calculates the difference of the two input links, for example,. Out = In1 In2.

Demo/Example Usage
Frame Diff, Median Pixel Replacement, Sync Variable Latency

Sapera APF Programmer's Manual

Sapera APF Reference 165

Memory Functions
The Memory functions provide access to the frame grabbers on-board RAM, FPGA memory resources.

Memory Function Library

FrameBuffer

Buffers the image stream in on-board RAM.

FrameCreateInitialized

Creates a frame buffer initialized with values.

Memory::FrameBuffer
Buffers the image stream in on-board RAM.

I/O Properties
Latency Type

Variable

Inputs

In, input data

Outputs

Out, output data

Parameters
XOffset

YOffset

XLength

YLength

FillLevel

X-coordinate of the upper left corner of the ROI, which is transmitted at the output link.
Run-time
changeable

Yes

Default

Range

0 Max image width

Y-coordinate of the upper left corner of the ROI, which is transmitted at the output link.
Run-time
changeable

Yes

Default

Range

0 Max image height

Width of the ROI, which is transmitted at the output link.

Run-time
changeable

Yes

Default

1024

Range

1 to (Max image width XOffset)

Height of the ROI, which is transmitted at the output link.

Run-time
changeable

Yes

Default

1024

Range

1 to (Max image height YOffset)

Provides the fill level of DRAM in 25% steps.

Sapera APF Programmer's Manual

Sapera APF Reference 166

Overflow

MemoryBank

Run-time
changeable

Run-time read-only

Default

Range

0-100%

Indicates a buffer overflow.

Run-time
changeable

Run-time read-only

Default

Range

0-1

Specifies the memory bank to use for the frame buffer.

Run-time
changeable

No

Default

DDR

Range

DDR, RLDRAM0, RLDRAM1, RLDRAM2, RLDRAM3

Description
The FrameBuffer function buffers the image stream in on-board DDR or RLDRAM (512MB DDR and 4 x 36MB RLDRAM on the Xcelera VX4 frame
grabber). In addition, this function additionally features region-of-interest (ROI) support.
Since the function uses hardware DDR or RLDRAM, the total number of input bits (Bit Width x Parallelism) must not exceed 128 bits for DDR, and 32 bits for
RLDRAM. The maximum image size must not exceed 36 MB for RLDRAM or 512MB for DDR.
To measure the fill level of the buffer the function provides 2 registers:

FillLevel shows the percentage fill level of DDRRAM in 25% steps.

Overflow parameter is set to 1 when FillLevel is close to or is 100% and the next image to be stored in the buffer will exceed the RAM capacity.
For more information see the Using Buffers section.

Demo/Example Usage
Frame Diff, Simple Buffer DDR, SimpleBuffer RLDRAM, Sync Memory Banks

Sapera APF Programmer's Manual

Sapera APF Reference 167

Memory::LineBuffer
Buffers the image stream in FPGAs internal memory.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, output data

Parameters
StoredLines

Number of lines to be stored in the FPGA. The amount of RAM reserved gows linear with the parameter Max. Img. Width and
StoredLines.
Run-time
changeable

FillLevel

InfiniteSource

No

Default

Range

limited by FPGA resources

Provides the memory fill level in 25% steps.

Run-time
changeable

Run-time read-only

Default

Range

0-100%

Activates support for dropping lines when there is a buffer overflow.

Run-time
changeable

No

Default

DISABLED

Range

ENABLED, DISABLED

Description
The LineBuffer function buffers a specified number of lines from the image stream, set using the StoredLines parameter, in internal FPGA block rams.
The function can be used as a buffer between normal Sapera APF functions as well as a buffer for an infinite source like camera functions.
To measure the fill level of the buffer the function provides FillLevel registers. FillLevel shows the percentage fill level of RAM and can be used at run-time to
detect buffer overflow conditions.
The parameter InfiniteSource should be set to DISABLED except in particular cases where its input is connected to a function that cannot handle flow control
signals. When InfiniteSource is set to ENABLED, the LineBuffer function will start dropping lines instead of instructing its input link to stop accepting data.

Demo/Example Usage
Sync Variable Latency

Sapera APF Programmer's Manual

Sapera APF Reference 168

PixelControl Functions
The PixelControl functions to extract information from individual pixels, such as the X and Y coordinates, significant bits, as well
as split or merge different pixel streams.

PixelControl Function Library

BitsExtract

Extracts n consecutive bits from the input pixel stream..

FrameCount

Outputs the number of the current image at the input link.

KeepLSB

Changes the bit width by selecting the lower bits of the input.

KeepMSB

Changes the bit width by selecting the higher bits of the input.

ParallelMerge

Merges multiple input links to a single output link by concatenating the input links parallelwise.

ParallelSplit

Splits the input link with PixelsPerClock=N into N output links with PixelPerClock=1

PixelHold

Outputs the last input pixel for which the Capture input was 1.

PixelMerge

Merges pixels of multiple input links into one pixel.

SelectFromParallel

Extracts a single pixel from the the input link.

XPos

Provides at the output link the X coordinate of the current pixel at the input link.

YPos

Provides at the output link the Y coordinate of the current pixel at the input link.

Sapera APF Programmer's Manual

Sapera APF Reference 169

PixelControl::BitsExtract
Extracts n consecutive bits from the input pixel stream.

I/O Properties
Fixed

Latency Type
Inputs

In, data input (grayscale only)

Outputs

Out, data output

Parameters
BitOffset

Defines the offset from the first bit of the input link, which is mapped to bit 0 at the output link.
Run-time
changeable

No

Default

Range

0-(number of extracted bits -1)

Description
Extracts consecutive bits from the input pixel stream. The number of extracted bits is defined by the BitWidth property of the output link.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 170

PixelControl::FrameCount
Outputs the number of the current image at the input link.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Parameters
SingleShot

Controls the wrap around condition. When set to OFF, the counter will count infinitely with each processed image, that is, a wrap around
will occur at the maximum value defined by the output link bit width resolution.
When set to ON, the counter keeps counting until the maximum possible value is reached. At maximum value the counter stops counting and
keeps the value.
Run-time
changeable

Yes

Default

OFF

Range

ON, OFF

Description
The FrameCount function outputs the number of the current image at the input link. The start image number is 0.

Demo/Example Usage
Not available

PixelControl::KeepLSB
Changes the bit width by keeping least significant bits (the lower bits) of the input.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The KeepLSB function changes the bit width by selecting the lower bits of the input. This number of bits is defined by the BitWidth property of the output link.
If the bit width of the output is larger than the bit width of the input, sign extension is done to provide the extra bits.

Demo/Example Usage
Auto Gain, Gaussian5x5, Sobel Edge

Sapera APF Programmer's Manual

Sapera APF Reference 171

PixelControl::KeepMSB
Changes the bit width by keeping most significant bits (the higher bits) of the input.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The function KeepMSB tries to preserve as much information as possible by adjusting the data sign and bit width to the desired output pixel format. The
algorithm is twofold:
1. Change the input by clipping

unsigned int to signed int: preserves the pixel value

Signed int to unsigned int : clipping to positive values, for example, if value > 0 it remains unchanged, and set to 0 otherwise
2. Change the BitWidth by keeping the relative brightness

if the output bit width is increased, the value is left-shifted to meet the desired bit width

if the output bit width is decreased, the value is divided by 2^n and rounded to meet the desired bit width.
Note that for multi component formats like RGB, the conversion is performed on each component separately.

Demo/Example Usage
Auto Gain, Auto-Threshold, Bayer, ColorSegment, Flat Line Correction, Sobel Edge

Sapera APF Programmer's Manual

Sapera APF Reference 172

PixelControl::ParallelMerge
The function merges N input links to a single output link by concatenating the input links parallelwise.

I/O Properties
Latency Type

Fixed

Inputs

In0 InN, image

Outputs

Out, data output

Description
The function merges N input links to a single output link by concatenating the input links parallelwise.
To set the number of input ports, select the Input node and specify the required parameter value.

The following images illustrate 2 cases: case A - 3 input links with PixelsPerClock =1, case B - 3 input links with PixelsPerClock= 2.

The input parallel pixels are concatenated to a single output link with PixelsPerClock = 3. The input link order determines the position of the correspondent
pixel in the output parallel word.

Note that input pixels in this case are also concatenated to the output parallel word and are not interleaved. The 3 input links with PixelsPerClock =2 are
concatenated to the output link with PixelsPerClock=6.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 173

PixelControl::ParallelSplit
Splits the input link with PixelsPerClock=N into N output links with PixelPerClock=1.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out [0 output links PixelPerClock - 1], data output

Description
The ParallelSplit function splits the input link with PixelsPerClock = N into N output links with PixelsPerClock =1. The amount of output links N has to be
specified on function creation. The amount of links has to be equal to the value of the input links PixelPerClock and cannot be changed after function creation.
To set the number of output ports, select the Output node and specify the required parameter value.

The following figure illustrates an example for input with PixelsPerClock =4.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 174

PixelControl::PixelHold
Outputs the last input pixel for which the Capture input was 1.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Capture, binary signal to enable the register
Out, data output

Outputs

Parameters
AutoClear

Selects whether to reset the register to the Init value at end of line (EoL), end of frame (EoF) or never (None).
Run-time changeable

Init

No

Default

EoL

Range

EoL, EoF, None

Defines the initialization value for the register function at design start up, after a design reset, a clear after end of line, and a clear after end of
frame. For color and multi component formats, the parameter Init defines the initialization value for each component, that is, all components
will be initialized with the same value.
Run-time changeable

No

Default

Range

For gray-scale input images, the range of output values is the same as the range of input pixel values.
For color or multi-components input images, output range is the same as each input components
range.

Description
The PixelHold function outputs the value of an internal data register. This data register is updated to the current value of the pixel at the In input when the
Capture input pixel is 1.
Additionally, it is possible to reset the the register to an initial value, specified by the Init parameter, at an end of line or end of frame.
For multi component formats like RGB, the initialization value defined by the Init parameter applies to every single component, that is, all components will be
initialized with the same initialization value.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 175

PixelControl::PixelMerge
Merges pixels of multiples input links into one pixel.

I/O Properties
Latency Type

Fixed

Inputs

In0 In N-1, image

Outputs

Out, data output

Description
The PixelMerge function merges pixels of N input link into one output pixel higher BitWidth. The output pixel is composed from the input pixels using the least
significant bits from the 1st input link to the most significant bits from the last input link.
The value of PixelPerClock should be the same for all input links but the value of BitWidth can vary.
To set the number of input ports, select the Input node and specify the required parameter value.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 176

PixelControl::SelectFromParallel
Extracts a single pixel from the the input link.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Parameters
ParNum

Defines which of the pixels of the input link is available at the output.
Run-time
changeable

No

Default

Range

Depends on PixelPerClock of the input link

Description
The SelectFromParallel function extracts a single pixel from the the input link and makes this value available at the output link.

Demo/Example Usage
Not available

PixelControl::XPos
Outputs the X coordinate of the current pixel.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The function XPos outputs the X coordinate of the current pixel at the input link.

Demo/Example Usage
Flat Line Correction

Sapera APF Programmer's Manual

Sapera APF Reference 177

PixelControl::YPos
Outputs the Y coordinate of the current pixel.

I/O Properties
Latency Type

Fixed

Inputs

In, image

Outputs

Out, data output

Description
The function YPos outputs the Y coordinate of the current pixel at the input link.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 178

Signal I/O Functions

The Signal I/O functions provide the functionality for controlling I/O signals.

Signal I/O Function Library

CC1, CC2, CC3, CC4

Provides access to the camera control signals.

ClockGenerator

Generates a periodic signal with adjustable frequency.

Debounce

Suppresses fast changing edges at the input signal with adjustable minimum time.

Delay

Delays the input signal for an adjustable time.

EdgeToPulse

Generates a short pulse when a rising, falling or both rising and falling edges are detected.

FlipFlop

Implements a "set-reset" FlipFlop.

FrameEndPulse

Generates a short pulse when the last pixel of a frame is detected.

FrameTrigIn0, FrameTrigIn1

Provides access to the frame grabbers frame trigger inputs.

FrameTrigOut0, FrameTrigOut1

Provides access to the frame grabbers frame trigger signal.

FrameStartPulse

Generates a short pulse when the first pixel of a frame is detected.

FreqReduce

Lowers the frequency of the input signal by an adjustable factor.

GPI0, GPI1, GPI2, GPI3

Provides access to the frame grabbers general-purpose input pins.

GPO0, GPO1, GPO2, GPO3

Provides access to the frame grabbers general-purpose output pins.

Gate

Controls the flow of images between input and output depends on the input signal Gate.

LineEndPulse

Generates a short pulse when the last pixel of a line is detected.

LineStartPulse

Generates a short pulse when the first pixel of a line is detected.

PeriodToPixel

Converts an input signal to a pixel stream with values representing the period of the signal.

PhaseDiffToPixel

Converts an input signal to a pixel stream with values that represent the phase difference of
two input signals.

PixelHighPulse

Generates a short pulse when a pixel with value 1 is detected.

PixelPeriodToPulse

Converts an image data stream with values that represent the period of a signal, into an
output signal with a defined period.

PixelRead

Allows the reading of the pixel status by software.

PixelToSignal

Converts from image domain to signal domain.

PulseWidthIncrease

Increases the pulse width of the input signal.

PulseWidthLimit

Limits the maximum pulse width of the input signal with adjustable maximum width.

PulseWidthToPixel

Converts an input signal in a data stream to a pixel stream with values that represents the
width of the high phase of the signal.

SignalHigh

Provides a signal with the constant value 1 (HIGH).

SignalInvertCond

Controls the polarity of the signal.

SignalLow

Provides a signal with the constant value 0 (LOW).

SignalMux

Selects a signal source from N signal sources and bypasses it to the output.

SignalRead

Allows the reading of the signal status by software.

SignalSync

Synchronizes a number of input links for a master signal.

SignalToPixel

Converts a signal stream into an 0D image.

SignalWrite

Allows the setting of the signal status by software.

Sapera APF Programmer's Manual

Sapera APF Reference 179

Signal I/O::CC1, CC2, CC3, CC4

Provides accces to camera control signals.

I/O Properties
Latency Type

Variable

Inputs

Signal input

Description
Provides accces to set camera control signals. Refer to the Camera signals: CC1 to CC4 section for more details.

Demo/Example Usage
CC1 Variable Period and Variable Width, GPI To CC1

Signal I/O::ClockGenerator
Generates a periodic signal with adjustable frequency.

I/O Properties
Latency Type

Fixed

Inputs

Tick, prescaler clock input (bit width = 1)

Gate, enable input

Outputs

Out, signal data output

Parameters
Period

Sets the period of generated pulses.

Run-time
changeable

PeriodBits

Sequence

SequenceBits

Yes

Default

65535

Range

265535

Number of bits required to encode the value specified by the Period parameter.
Run-time
changeable

No

Default

16

Range

2..64

Specifies the amount of pulses to be generate by rising edges of the Gate input.
Run-time
changeable

Yes

Default

Range

0..65535

Number of bits required to encode the value specified by the Sequence parameter..
Run-time
changeable

No

Default

16

Sapera APF Programmer's Manual

Sapera APF Reference 180

Range

2..64

Description
The ClockGenerator function produces a periodic signal with a controllable frequency. The width of generated pulses is equal to the design clock period.
The pulse generation can be enabled for a set period of time. The function also supports generation of sequences of pulses.
The frequency is controlled by the parameter Period. The period is measured in the number of high pulses on the Tick input. If the Tick input is connected to a
constant HIGH value (using the Signal I/O::SignalHigh function), the period is instead counted as a multiple of the FPGAs design clock frequency.
Pulse generation starts when the Gate input is active (high). The Gate input can be used for synchronization as well as for controlling the amount of generated
pulses. When the Gate input is LOW, the function output will be LOW too. Pulse generation and the running sequence will be interrupted upon assertion of a
LOW value at the Gate input.
The parameter Sequence allows generation of sequences of pulses for every rising edge of the Gate input. If Sequence is set to zero (default), the pulse
generation continues infinitely while the Gate input is HIGH. If the Sequence parameter value is greater than zero, the function will generate this number of
pulses of the specified period for every rising edge of Gate as long as the Gate input is set to HIGH.

The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
CC1 Variable Period and Variable Width

Sapera APF Programmer's Manual

Sapera APF Reference 181

Signal I/O::Debounce
Suppresses fast changing edges at the input signal using an adjustable minimum time.

I/O Properties
Latency Type

Fixed

Inputs

In, signal data input

Tick, prescaler clock input (bit width = 1)
Out, signal data output

Outputs

Parameters
Debounce

Sets the minimum signal duration, measured in pulses on the Tick input

DebounceBits

Run-time
changeable

Yes

Default

Range

265535

Number of bits required to encode the value specified by the Debounce parameter.
Run-time
changeable

No

Default

16

Range

2..64

Description
The Debounce function suppresses fast signal changes on the input link . Constant signals that meet the minimal time duration are sent to the output, otherwise
they are ignored.
The parameter Debounce specifies the minimum time the input signal must be HIGH or LOW without changing its level. This time is measured by the Tick
input being HIGH, that is, the Tick acts like a prescaler input. If the Tick input is set to a constant HIGH value (using the Signal I/O::SignalHigh function), the
debounce function counts the signal duration at the design clock frequency.
If Debounce is set to N, the function only sends the output signals whose state remains unchanged for N cycles, or ticks (when Tick was HIGH). Any input
signal changes, for example, changing from HIGH to LOW or vice versa will be suppressed and reset the debounce counter.
Note that the function acts also like a delay element. Any signal changes that meet the debounce specification of being unchanged for N Ticks will be passed to
the function output after the delay of N Ticks. However the pulse form stays unchanged.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 182

Signal I/O::Delay
Delays the input signal for an adjustable time.

I/O Properties
Latency Type

Fixed

Inputs

Tick, prescaler clock input (bit width = 1)

In, signal data input
Out, signal data output

Outputs

Parameters
Delay

Delays input pulses for the specified value in Ticks.

DelayBits

Run-time
changeable

Yes

Default

32768

Range

065535

Number of bits required to encode the value specified by the Delay parameter.
Run-time
changeable

No

Default

16

Range

2..64

Description
The function delays the input signal for the amount of Tick HIGH cycles specified by the parameter Delay. If Tick is connected to a constant HIGH value (using
the Signal I/O::SignalHigh function), the function counts the delay at the FPGAs design clock frequency. Tick acts like a prescaler.
The function can delay only one pulse at time, that is, any more occurances of rising and falling edges will be ignored during the delay processing. The input
signal will be blocked for the duration of delay phase.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 183

Signal I/O::EdgeToShortPulse
Generates a short pulse when a rising, falling or both rising and falling edges are detected.

I/O Properties
Latency Type

Fixed

Inputs

In, signal data input (bit width =1)

Outputs

Out, signal data output

Parameters
Edge

Specifies the edge type the function will trigger to.

RisingEdge = triggering to all input signal changes from low to high

FallingEdge = triggering to all input signal changes from high to low

BothEdges = triggering to any input signal changes.

Run-time changeable

No

Default

RisingEdge

Range

RisingEdge, FallingEdge, BothEdges

Description
Generates a pulse of one FPGAs design clock, when a rising edge, falling edge, or either of both type of edges (rising or falling) is detected. The parameter
Edge specifies the type of edge the function triggers to.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 184

Signal I/O::FlipFlop
Implements a "set-reset" flip-flop.

I/O Properties
Latency Type

Fixed

Inputs

Set, signal data input (bit width =1)

Reset, signal data input (bit width =1)

Outputs

Out, signal data output

Parameters
Priority

Specifies the behaviour of the function for the case when both the Set and Reset inputs are set to HIGH simultaneously. Possible values are:

RESET = the value on the output link Out will be set to LOW.

SET = the value on the output link Out will be set to HIGH.
Run-time
changeable

Init

No

Default

Reset

Range

Reset, Set

Specifies the start up value (after a design global reset) for the output link Out.
Run-time
changeable

No

Default

Range

0, 1

Description
The function implements a Set-Reset flip flop. If the input Set is HIGH, the function sets the output value to HIGH as well and keeps it until Reset is set to
HIGH. When Reset is set to HIGH, the output value on Out is reset to LOW.
The parameter Priority specifies what happens when the Set and Reset inputs are both set to HIGH. If Priority is set to RESET, the function will reset the output
to LOW. If Priority is set to SET, the function will set the output to HIGH.
The parameter Init specifies the start up initialization value for the register. It is either 0 (LOW) or 1 (HIGH).

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 185

Signal I/O::FrameEndPulse
Generates a short pulse when the last pixel of a frame is detected.

I/O Properties
Fixed

Latency Type
Inputs

In, image data input

Outputs

Out, signal data output (bit width = 1)

Description
The function generates a pulse with a duration of 1 cycle of the FPGAs design clock when the last frame pixel is detected.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of
Sapera APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Signal I/O::FrameTrigIn0, FrameTrigIn1

Provides access to the frame grabbers frame trigger inputs.

I/O Properties
Latency Type

Variable

Outputs

Out, signal data output

Description
Provides access to the frame grabbers frame trigger inputs. Refer to the Frame triggers and line triggers section and the frame grabber documention for more
information on the available input triggers and their specifications.

Demo/Example Usage
External Frame Trigger

Sapera APF Programmer's Manual

Sapera APF Reference 186

Signal I/O::FrameTrigOut0, FrameTrigOut1

Provides access to the frame grabbers frame trigger signal.

I/O Properties
Latency Type

Variable

Inputs

In, signal data input

Description
Provides access to the frame grabber output triggers. Refer to the Frame triggers and line triggers section and the the frame grabber documention for more
information on the available frame trigger signals.

Demo/Example Usage
External Frame Trigger

Signal I/O::FrameStartPulse
Generates a short pulse when the first pixel of a frame is detected.

I/O Properties
Latency Type

Variable

Inputs

In, image data input

Outputs

Out, signal data output (bit width = 1)

Description
The function generates a pulse with a duration of 1 cycle of the FPGAs design clock when the first frame pixel is detected.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 187

Signal I/O::FreqReduce
Lowers the frequency of the input signal by an adjustable factor.

I/O Properties
Latency Type

Fixed

Inputs

In, signal data input (bit width = 1)

Outputs

Out, downscaled signal data output (bit width = 1)

Parameters
Downscale

MaxScaleBits

Specifies the amount of pulses to be suppressed between 2 output pulses.

Run-time
changeable

Yes

Default

Range

1 to (2^MaxScaleBits-1)

The amount of bits required to encode the maximum Downscale value.

Run-time
changeable

No

Default

Range

2 to 32

Description
The FreqReduce function downscales the input signal to the specified frequency. That is, only every Nth pulse will be forwarded to the output and the pulses 1
to N-1 will be suppressed.
The parameter Downscale specifies the amount of pulses to suppress before forwarding a pulse on the input link to the output link.
The parameter MaxScaleBits specifies the amount of bits needed to encode the maximum downscale value, that is, Downscale can be in range from 1 to 2 ^
MaxScaleBits - 1.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 188

Signal I/O::GPI0, GPI1, GPI2, GPI3

Provides access to the frame grabbers general-purpose input pins.

I/O Properties
Latency Type

Variable

Outputs

GPI_x, signal data output

Description
The general purpose input (GPI) functions provides a connection to the input pins on the frame grabbers external connector. Refer to the frame grabber
documentation for pin out information and the input pinss electrical specifications.

Demo/Example Usage
GPI To CC1, GPI Select Processing Path, Read/Write General Purpose IOs

Signal I/O::GPO0, GPO1, GPO2, GPO3

Provides access to the frame grabbers general-purpose output pins.

I/O Properties
Latency Type

Variable

Inputs

GPO_x, signal data input

Description
The general purpose output (GPO) functions provides a connection to the output pins on the frame grabbers external connector. Refer to the frame grabber
documentation for pin out information and the output pinss electrical specifications.

Demo/Example Usage
CC1 Variable Period and Variable Width, Read/Write General Purpose IOs, Saturation Detection

Signal I/O::Gate
Controls the flow of images between input and output using a gate input signal.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input

Outputs

Out, image data output

Gate, signal data input (bit width =1)

Description
The Gate function controls the image flow between In and Out ports in accordance with the control signal Gate.
The input frames are bypassed to the function output when Gate is activated. Evaluation of the frame being passed or blocked at the frames first pixel. If the
Gate input is HIGH, the frame is passed. If the Gate is inactive, the frame is blocked.
If the Gate input becomes LOW while the frame is not completely passed to the function output, the function will still finish forwarding that complete frame to
its output before switching into the blocking mode.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 189

Signal I/O::LineEndPulse
Generates a short pulse when the last pixel of a line is detected.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input

Outputs

Out, signal data output (bit width = 1)

Description
The function generates a pulse with a duration of 1 cycle of the FPGAs design clock on its output when the last line pixel is detected.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Signal I/O::LineStartPulse
Generates a short pulse when the first pixel of a line is detected.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input

Outputs

Out, signal data output (bit width = 1)

Description
The LineStartPulse function generates a pulse with a duration of 1 cycle of the FPGAs design clock on its output when the first line pixel is detected.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 190

Signal I/O::PeriodToPixel
Converts an input signal to a pixel stream with values representing the period of the signal

I/O Properties
Variable

Latency Type

In, signal data input (bit width = 1)

Inputs

Tick, prescaler clock signal input (bit width = 1)

None

Outputs

Parameters
MaxPeriodBits

Specifies the amount of bits required to represent the maximum possible period.
Run-time
changeable

No

Default

Range

2 to 64

Description
The function converts the input signal to a pixel stream representing the period of the input signal.
The period is measured in Ticks being HIGH, that is, Tick is a prescaler signal. If the Tick input is connected to a constant HIGH (using the Signal
I/O::SignalHigh function), the function counts the period at the FPGAs design clock frequency.
The parameter MaxPeriodBits specifies the amount of bits needed to encode the maximum possible period. When the measured period exceeds [2 ^
MaxPeriodBits] the output period will be set to the maximum representable value, that is [2 ^ MaxPeriodBits - 1].
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 191

Signal I/O::PhaseDiffToPixel
Converts an input signal to a pixel stream with values that represent the phase difference of two input signals.

I/O Properties
Latency Type

Variable

Inputs

In0, signal data input (bit width = 1)

In1, signal data input (bit width = 1)
Tick, prescaler clock signal input
Out, image data output

Outputs

Parameters
MaxDelayBits

Specifies the amount of bits required to represent the maximum possible phase difference between input signals In0 and In1.
Run-time changeable

No

Default

Range

2 to 64

Description
The function converts the input signal to a pixelstream representing the phase difference between input signals In0 and In1.
The phase difference is measured in Ticks being HIGH. That is, Tick is a prescaler signal. If the Tick input is connected to a constant HIGH, the function counts
the delay at design clock frequency.
The parameter MaxDelayBits specifies the amount of bits needed to endcode the maximum possible phase difference. When the measured delay exceeds [2 ^
MaxDelayBits] the output delay will be set to the maximum representable value, i.e. [2 ^ MaxDelayBits - 1].
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 192

Signal I/O::PixelHighPulse
Generates a short pulse when a pixel with value 1 is detected.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input (bit width = 1)

Outputs

Out, signal data output (bit width = 1)

Description
The function generates a pulse with a duration of 1 cycle of the FPGAs design clock for each pixel at the input link In with the value ONE (binary image).
Pauses in the input image stream are interpreted by the function as invalid pixels and the function output becomes LOW.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Signal I/O::PixelPeriodToPulse
Converts an image data stream with values that represent the period of a signal, into an output signal with a defined period.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input (bit width = 1)

Outputs

Out, signal data output (bit width = 1)

Description
The function converts the input stream of pixels into a signal with the period provided by the pixel values. The function generates pulses with a duration of 1
cycle of the FPGAs design clock on its output with the provided period.
During processing of the signal generation with the specified period, the function will ignore all new values on the input stream. When the processing is finished
and the function generates a pulse on its output, the latest valid value that was provided on the input link will be interpreted as the new period. The next pulse on
function output will be generated with that period.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 193

Signal I/O::PixelRead
Allows the reading of the pixel status by software.

I/O Properties
Latency Type

Fixed

Inputs

In, image data input

Outputs

None

Parameters
Status

Implements a register for monitoring the latest valid value on the input pixel stream.
Run-time
changeable

Yes

Default

N/A

Range

N/A

Description
The PixelRead function monitors the state of the input pixel stream and provides a register for reading out the latest valid
value by software.
The latest valid value on the pixel stream is stored in the register Status, which is readable by software.

Demo/Example Usage
Not available

Signal I/O::PixelToSignal
Converts from image domain to signal domain.

I/O Properties
Latency Type

Variable

Inputs

In, image data input (bit width = 1)

Outputs

Out, signal data output

Description
The PixelToSignal function converts the input from the image domain to the signal domain. The image domain can be an
image and or pixel stream. The output domain of the function is a signal data output.
The signal domain defines signals to be valid infinitely. However, in the image domain the existence of pauses between valid
pixels is possible. The function stores internally the last valid pixel that was detected on its input. The value of this stored pixel
is output during pause periods. When input is not paused, the value of the input propagates to the output.

Demo/Example Usage
Saturation Detection

Sapera APF Programmer's Manual

Sapera APF Reference 194

Signal I/O::PulseWidthIncrease
Increases the pulse width of the input signal.

I/O Properties
Latency Type

Fixed

Inputs

Tick, prescaler clock input

In, signal data input
Out, signal data output

Outputs

Parameters
Width

Specifies the width of the generated pulses, measured in Tick pulses.

WidthBits

Run-time
changeable

Yes

Default

32768

Range

1 to 65535

Number of bits required to encode the value specified by Width.

Run-time
changeable

No

Default

16

Range

2 to 64

Description
The function produces a pulse on the output link for every rising edge of the input signal. The parameter Width specifies the pulse width. The width is measured
in pulses of the Tick clock input being HIGH, that is, the Tick is a prescaler signal. If the Tick input is connected to a constant HIGH, the function counts the
pulse width at the design clock frequency.
Any occurances of following rising edges on the input link are ignored during generation of the current pulse.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 195

Signal I/O::PulseWidthLimit
Limits the maximum pulse width of the input signal.

I/O Properties
Latency Type

Fixed

Inputs

Tick, prescaler clock input

In, signal data input
Out, signal data output

Outputs

Parameters
MaxWidth

Limits the input pulses to the specified pulse width, measured in Tick pulses.

MaxWidthBits

Run-time changeable

Yes

Default

32768

Range

1 to 65535

Number of bits required to encode the value specified by MaxWidth.

Run-time changeable

No

Default

16

Range

2 to 64

Description
The function limits the maximum pulse width of the input signal. The maximum allowed pulse width is specified by the parameter MaxWidth. The width is
measured in pulses of the Tick clock input being HIGH, that is, the Tick is a prescaler signal. If the Tick input is connected to a constant HIGH, the function
counts the pulse width at the design clock frequency.
If the width of an input pulse is shorter than the maximum allowed width, the pulse is passed unchanged. If the input pulse exceeds the maximum width, the
pulse width is clipped to the MaxWidth value before being sent to the output.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 196

Signal I/O::PulseWidthToPixel
Converts an input signal in a data stream to a pixel stream with values that represents the width of the high phase of the signal.

I/O Properties
Latency Type

Fixed

Inputs

Tick, prescaler clock input

In, signal data input
Out, image data output

Outputs

Parameters
MaxWidthBits

Number of bits required to encode the pulse width.

Run-time changeable

No

Default

Range

2 to 64

Description
The function converts the input signal to a pixel stream with values representing the pulse width of the input signal.
The width is measured in pulses of the Tick clock input being HIGH, that is, the Tick is a prescaler signal. If the Tick input is connected to a constant HIGH, the
function counts the pulse width at the design clock frequency.
The parameter MaxWidthBits specifies the amount of bits needed to endcode the maximum possible pulse width. When the measured width exceeds [2 ^
MaxWidthBits] the output pulse width will be set to the maximum representable value, that is, [2 ^ MaxWidthBits - 1].
On the Xcelera-VX4, as of release 1.0 of Sapera APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Signal I/O::SignalHigh
Provides a signal with a constant value 1 (HIGH).

I/O Properties
Latency Type

Fixed

Inputs

None.

Outputs

Out, signal data output (bit width = 1)

Description
Provides a signal with a constant value 1 (HIGH).

Demo/Example Usage
CC1 Variable Period and Variable Width

Sapera APF Programmer's Manual

Sapera APF Reference 197

Signal I/O::SignalInvertCond
Controls the signal output polarity.

I/O Properties
Latency Type

Fixed

Inputs

In, signal data input

Outputs

Out, signal data output (bit width = 1)

Parameters
Invert

Specifies the polarity of the output signal.

NonInvert = the input is passed to the output.

Invert = the output signal is an inverted copy of the input signal.

Run-time
changeable

Yes

Default

NotInvert

Range

NotInvert, Invert

Description
Controls the signal output polarity using the Invert parameter which can be modified at run-time by the host application.

Demo/Example Usage
CC1 Variable Period and Variable Width

Signal I/O::SignalLow
Provides a signal with a constant value 0 (LOW).

I/O Properties
Latency Type

Fixed

Inputs

None.

Outputs

Out, signal data output (bit width = 1)

Description
Provides a signal with a constant value 0 (LOW).

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 198

Signal I/O::SignalMux
Selects a signal source from among N signal sources and sends it to the output.

I/O Properties
Latency Type

Fixed

Inputs

In [0 (N-1)], signal data input, N is in the range from 2 to 64

Outputs

Out, selected link from In [0 (N-1)]

Parameters
Select

Represents an index of the input link to send to the output.

Run-time
changeable

Yes

Default

Range

[0 (N-1)]

Description
The SignalMux function implements an N-input to 1-output multiplexer. The Select parameter controls which input is sent to the output.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 199

Signal I/O::SignalRead
Allows reading of the signal status by software.

I/O Properties
Latency Type

Fixed

Inputs

I [N], signal data input, N is in range from 0 to 64

Outputs

None

Parameters
Mode

Status

Specifies the monitoring type mode.

Direct = the input signal is directly connected to the status register.
Rise = the status register will be set when a rising edge of the input signal is detected.
Fall = the status register is set after detecting a falling edge of the input signal.
Edge = the status register is set with the detection of either a falling edge or a rising edge.
Pulse = the status register is set when detecting a pulse on the input signal, that is, a rising edge followed later by a falling edge.
Run-time
changeable

No

Default

Direct

Range

Direct, Rise, Fall, Edge, Pulse

The monitored signal status register. The status register is cleared after each reading out. Bit 0 corresponds with the signal link 0 and so on.
Run-time
changeable

Yes

Default

N/A

Range

N/A

Description
The function allows reading out of signal states by software. The type of signal monitoring is specified by the parameter Mode. The monitored signal values are
stored in the register Status and can be read out by software.
In Direct mode the signal status is read out directly without storing any of its history.
In Rise mode the status register is set to HIGH when an occurance of a rising edge on the input signal detected.
In Fall mode the status register is set to HIGH when the function detects a falling edge on the input link.
In Edge mode the status register is set to HIGH when a falling or a rising edge on the input link is detected.
In Pulse mode the status register is set to HIGH when the function detects a rising edge followed by a falling edge, that is. a complete pulse. The
status will be set with the detection of the falling edge.
In all 5 modes the status register is reset to 0 directly during the readout process of the status register. Thus, a sequential reading of the status register with the
input signal will lead to the 1st readout value being HIGH, assuming the trigger condition specified by the Mode register occurred, and the subsequent readouts
will return a value ZERO until the next occurance of the signal condition.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 200

Signal I/O::SignalToPixel
Converts a signal stream into a pixel stream.
I/O Properties
Latency Type

Fixed

Inputs

In, signal data input

Outputs

Out, image data input

Description
The function SignalToPixel converts a signal stream into a pixel stream. It generates a steady pixel stream (one pixel at each clock tick). The current signal
value is mapped on to a binary pixel: LOW converts to the value 0 and HIGH converts to the value 1.
Note, since signals are defined as being valid for the entire time, conversion from signal to pixel domain can cause data loss an element causes an inhibit. This
behavior is unavoidable due to the definition of signal validity.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 201

Signal I/O::SignalWrite
Allows the setting of the signal status by software.

I/O Properties
Latency Type

Fixed

Inputs

None

Outputs

Out, signal data input (bit width = 1)

Parameters
Mode

Specifies the status of the signal on the output link.

Low = the output signal is set to LOW.
High = the output signal is set to HIGH.
Pulse = a short pulse (LOW-HIGH-LOW) is out. Pulse width is 1 cycle of the FPGAs design clock.
Run-time
changeable

Yes

Default

Low

Range

Low, High, Pulse

Description
The function allows setting of signal states by software. The state type is specified by the parameter Mode.
The design clock setting depends on the type of front-end configuration used by the frame grabber. On the Xcelera-VX4, as of release 1.0 of Sapera
APF, the base FPGA frequencies are as follows:

Front-end

Base FPGA design frequency

80-bit designs
(10 taps/8 bits or 8 taps/10 bits):

112.5 MHz

All other front-ends

100 MHz

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 202

Statistics Functions
The Statistics functions provide the functionaity for generating line, column, and image statistics.

Statistics Member Functions

CountModulo

Counts the number of input pixels, lines or frames, and outputs this value modulo N.

FrameMax

Computes the maximum in a frame of pixels

FrameMin

Computes the minimum in a frame of pixels.

FrameSum

Computes the sum over all pixels in the frame.

Histogram

Calculates the histogram of the input images pixel values.

HorizontalMax

Computes the maximum of a sequence for pixels in the row

HorizontalMin

Computes the minimum of a sequence for pixels in the row.

HorizontalSum

Computes the sum of a sequence for pixels in the row.

PixelCountNonZero

Counts the number of all 1 pixels in a line or frame.

VerticalMax

Computes the maximum pixel value in a column.

VerticalMin

Computes the maximum pixel value in a column.

VerticalSum

Computes the sum of a sequence for pixels in a column.

Sapera APF Programmer's Manual

Sapera APF Reference 203

Statistics::CountModulo
Counts the number of input pixels, lines or frames, and outputs this value modulo N.

I/O Properties
Latency Type

Fixed

Inputs

In, image input (grayscale or RGB image)

Outputs

Out, data output

Parameters
Divisor

CountEntity

Defines the divisor N of the modulo operation.

Run-time
changeable

Yes

Default

Range

Depends bit width of the output link

Defines what the function counts :pixels, lines or frames.

Run-time
changeable

AutoClear

No

Default

PIXEL

Range

PIXEL, LINE, FRAME

The AutoClear option allows a clear of the counter at either the end of a line, the end of a frame or no clear at all.
If CountEntity is set to PIXEL, all three options can be selected. If CountEntity is set to LINE, only options EoF and NONE can be
selected. For a CountEntity FRAME, a clear of the counter is not possible.
Run-time
changeable

No

Default

NONE

Range

EoL (End of Line), EoF (End of Frame), NONE

Description
The CountModulo function counts the pixels, lines or frames at the input link and applies a modulo N operation. The Divisor parameter sets the base N of the
modulo count operation. For example, a divisor of 4 will output "count MOD 4", that is, 0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3 ...
The image dimensions of the output frames are always equal to the input frames. The pixel data at the output represents the modulo results.
The CountEntity parameter can be configured to either count every pixel, line or frame of the input link. If CountEntity is set to PIXEL, the function will enable
its counter with every pixel of the input. Note that the data values of the input link are not considered and therefore, are discarded; only the existence of a pixel is
taken into account.
The function also counts empty lines and empty frames with no pixels in it. The counter always starts with value zero. Setting the AutoClear parameter to EoL
or EoF restarts counting at a new line or a new frame.
Examples:
Divisor = 6, CountEntity = PIXEL, AutoClear = EoF
Frame 0

Sapera APF Programmer's Manual

Frame 1

Sapera APF Reference 204

Divisor = 6, CountEntity = LINE, AutoClear = NONE

Frame 0

Frame 1

Divisor = 6, CountEntity = FRAME, AutoClear = NONE

Frame 0

Frame 1

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 205

Statistics::FrameMax
Computes the maximum pixel value in a frame.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

IsMaxO, binary signal to indicate a new maximum

Description
The FrameMax function produces a frame synchronous to the input frame, where each pixel is replaced by the maximum value found in the image so far. The
last pixel in the output frame gives the maximum pixel value found in the input image.
If the current pixel is a new maximum just found, the output Link 'IsMaxO' is 1, otherwise it is 0.
The BitWidth of the output link IsMaxO scales with the PixelsPerClock of the input link to indicate the correct position of the new maximum.
With every new input frame the maximum detection starts again. Additionally, it is possible to clear the current maximum manually when the 'ClrI' link is set to
1. When a manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.
Example:

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 206

Statistics::FrameMin
Computes the minimum pixel value in a frame.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

IsMinO, binary signal to indicate a new maximum

Description
The FrameMin function produces a frame synchronous to the input frame, where each pixel is replaced by the minimum value found in the image so far. The last
pixel in the output frame gives the minimum pixel value found in the input image.
If the current pixel is a new minimum just found, the output Link 'IsMinO' is 1, otherwise it is 0.
The BitWidth of the output link IsMinO scales with the PixelsPerClock of the input link to indicate the correct position of the new minimum.
With every new input frame the minimum detection starts again. Additionally, it is possible to clear the current minimum manually when the 'ClrI' link is set to 1.
When a manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.
Example:

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 207

Statistics::FrameSum
Computes the sum of all pixels in a frame.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

Description
The FrameSum function produces a frame synchronous to the input frame, where each pixel is replaced by the current sum of all pixel values found in the image
so far. The last pixel in the output frame gives the sum of all pixel values in the input image.
With every new input frame the summation starts again. Additionally, it is possible to clear the current sum manually when the 'ClrI' link is set to 1. When a
manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.
Example:

Demo/Example Usage
Auto Gain, Auto-Threshold

Sapera APF Programmer's Manual

Sapera APF Reference 208

Statistics::Histogram
Calculates the histogram of the input images pixel values.

I/O Properties
Latency Type

Variable

Inputs

In, data input (grayscale image)

Outputs

Out, histogram output image

Parameters
AutoSync

Selects whether to output a histogram for every input line or every input frame.

EoF (End of Frame) produces a histogram image of height 1for every input frame.

EoL (End of Line) produces a histogram image with same height as the input image. A histogram is computed for each input image
line separately.
Run-time
changeable

No

Default

EoL

Range

EoL, EoF

Description
This function calculates the histogram of the input images pixel values. Depending AutoSync parameter setting, a new histogram is produced at each line or at
each frame.
Each line in the output image contains a histogram:
Each pixel position in the output line reflects the number of pixels found with a value equal to the position. For example, the 10th output pixel gives the
count of pixels in the input image whose value is 10.
The width of the output lines is 2^(the BitWidth of the input image). For example, for an 8-bits input image, each line will have 256 pixels.
The BitWidth of the output pixels will be automatically adjusted so that all input pixels can be counted even in the worst case (that is, all input pixels
have the same value).

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 209

Statistics::HorizontalMax
Computes the maximum pixel value in a line.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

IsMaxO, binary signal to indicate a new maximum

Description
The HorizontalMax function produces a frame synchronous to the input frame, where each pixel is replaced by the maximum value found in the very same row
so far. The last pixel in each output line gives the maximum pixel value found in the current input line.
If the current pixel is a new maximum just found, the output Link 'IsMaxO' is 1, otherwise it is 0.
With every new input line the maximum detection starts again. Additionally, it is possible to clear the current row manually when the 'ClrI' link is set to 1.
When a manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.

Demo/Example Usage
Saturation Detection

Statistics::HorizontalMin
Computes the minimum pixel value in a line.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscaleimage)

ClrI, binary control signal clear

Outputs

Out, data output

IsMinO, binary signal to indicate a new minimum

Description
The HorizontalMin function produces a frame synchronous to the input frame, where each pixel is replaced by the minimum value found in the very same row
so far. The last pixel in each output line gives the minimum pixel value found in the current input line.
If the current pixel is a new minimum just found, the output Link 'IsMinO' is 1, otherwise it is 0.
With every new input line the minimum detection for each row starts again. Additionally, it is possible to clear the current row manually when the 'ClrI' link is
set to 1. When a manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 210

Statistics::HorizontalSum
Computes the sum of pixel values in a line.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale 1D or 2D)

ClrI, binary control signal clear

Outputs

Out, data output

Description
The HorizontalSum function produces a frame synchronous to the input frame, where each pixel is replaced by the sum of all pixel values found in the very
same row. The last pixel in each output line gives the sum of all pixel values in the current input line.
With every new input line the sum is set to 0. Additionally, it is possible to clear the current sum manually when the 'ClrI' link is set to 1. When a manual clear
is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 211

Statistics::PixelCountNonZero
Counts the number of all 1 pixels in a line or frame.

I/O Properties
Latency Type

Fixed

Inputs

In, binary input image

ClrI, binary input image

Outputs

Out, data output

Parameters
AutoClear

Defines when to reset to counter to its initial value.

Run-time
changeable

Init

Default

EoL

Range

EoL (End of Line), EoF (End of Frame)

Defines the initial value. The counter is set to its initial value at:
a) start-up
b) when ClrI=1
c) by AutoClear (at EoL or EoF)
Run-time
changeable

Direction

No

No

Default

Range

0, maximum output value

Defines whether the counter is incremented (UP) or decremented (DOWN) on a '1' at the input link In.
Run-time
changeable

No

Default

UP

Range

UP, DOWN

Description
The PixelCountNonZero function counts non-zero pixels when the CtrI link is set to '1'. The initial output value is set by the Init parameter, and is either
incremented or decremented for each 1 input pixel, depending on the Direction parameter.
The BitWidth of the output link will be automatically adjusted according to the maximum dimensions of the input image.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 212

Statistics::VerticalMax
Computes the maximum pixel value in a column.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

IsMaxO, binary signal to indicate a new maximum

Description
The VerticalMax function produces a frame synchronous to the input frame, where each pixel is replaced by the maximum value found in the very same column
so far. The pixel at each position in the last line of the output frame gives the maximum pixel value found in the whole input frame for this column position.
If the current pixel is a new maximum just found, the output Link 'IsMaxO' is 1, otherwise it is 0.
With every new input frame the maximum detection for each colum starts again. Additionally, it is possible to clear the current column manually when the 'ClrI'
link is set to 1. When a manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.

Demo/Example Usage
Not available

Statistics::VerticalMin
Computes the minimum pixel value in a column.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

IsMinO, binary signal to indicate a new minimum

Description
The VerticalMin function produces a frame synchronous to the input frame, where each pixel is replaced by the minimum value found in the very same column
so far. The pixel at each position in the last line of the output frame gives the minimum pixel value found in the whole input frame for this column position.
If the current pixel is a new minimum just found, the output Link 'IsMinO' is 1, otherwise it is 0.
With every new input frame the minimum detection for each colum starts again. Additionally, it is possible to clear the current colum manually when the 'ClrI'
link is set to 1. When a manual clear is not necessary, ensure a constant 0 at 'ClrI', to enable normal operation.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 213

Statistics::VerticalSum
Computes the sum of pixel values in a column.

I/O Properties
Latency Type

Fixed

Inputs

In, data input (grayscale image)

ClrI, binary control signal clear

Outputs

Out, data output

Description
The vertical sum function produces a frame synchronous to the input frame, where each pixel is replaced by the sum of all pixel values found in the very same
column. The pixel at each position in the last line of the output frame gives the sum of pixel values in the whole input frame for this column position.
With every new input frame the sum is set to 0. Additionally, it is possible to clear the current column sum manually when the 'ClrI' link is set to 1. When a
manual clear is not necessary, ensure a constant 0 at 'ClrI' to enable normal operation.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 214

StreamControl Functions
The StreamControl functions provide the functionality manipulating the data streams.

StreamControl Function Library

BranchCreate

Clones the input link to a user-specified number of output links.

BranchEnable

Enables or disables the flow of images through the function, based on a parameter value.

BranchSync

Synchronizes image streams.

FrameAppend

Vertically concatenates N consecutive input images into a single taller output image.

FrameInsert

Performs conditional time-division multiplexing of multiple images into a single output link.

FrameInsertInitial

Creates an initial image frame for inter-frame processing.

FrameMux

Selects an image between between multiple input links.

FrameRemoveCond

Enables or disables the flow of images through the function, based on an input value.

FrameSplit

Separates input images into consecutive output images of height N.

LineAppend

Horizontally appends N lines into a single wider output line.

LineCarry

Expands the last line of an image into the next image.

LineInsert

Performs conditional time-division multiplexing of multiple lines into a single output link.

LineRemoveCond

Enables or disables the flow of lines through the function, based on an input value.

LineSplit

Separates input lines into consecutive lines of width N.

Parallelize

Increases the value of PixelsPerClock.

PixelCarry

Expands the last pixel of a line or an image into the next line or image.

PixelCarryEOF

Expands the last pixel of an image into a new image.

PixelMux

Selects a pixel between between multiple input links.

PixelRemoveCond

Enables or disables the flow of pixels through the function, based on an input.

PixelSync

Formats a pixel stream into images.

RectangleReshape

Formats variable width input images into a fixed rectangular size.

Serialize

Decreases the value of PixelsPerClock.

Trash

Provides a data sink for unused links.

Sapera APF Programmer's Manual

Sapera APF Reference 215

StreamControl::BranchCreate
Clones the input link to a user-specified number of output links.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out [0 63], data output

Description
The BranchCreate function clones the input link to a user set number of output links.
To set the number of output links, select the output link and specify the required value in the Properties dialog.

Demo/Example Usage
Auto Gain, Auto-Threshold, ColorSegment, ExtractKernel, Flat Line Correction, Median Pixel Replacement, Multiple Outputs, Simple Processing, Sobel Edge,
Variable Output Dimensions

Sapera APF Programmer's Manual

Sapera APF Reference 216

StreamControl::BranchEnable
Enables or disables the flow of images through the function, based on a parameter value.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
I Format

O Format

EnableBranch

Expected pixel format at the input

Run-time
changeable

No

Default

gray8x8

Range

gray8x8, gray16x4, rgb24x2

Target pixel format at the output. Should be set to the same value as I Format.
Run-time
changeable

No

Default

gray8x8

Range

gray8x8, gray16x4, rgb24x2

Selects if images flow through the function

Run-time
changeable

Yes

Default

0 (disabled)

Range

0 (disabled), 1 (enabled)

Description
The BranchEnable function enables the image flow through the function when the EnableBranch parameter is set to 1, otherwise the function outputs nothing
(that is, data is sent to trash). There are two typical uses for this function:
If parallel branches at the output of a StreamControl::BranchCreate function have different maximum throughputs, the BranchEnable function can be
put in front of the branches with lower bandwidth. This will let the other branches run at their maximum bandwidth. For example, this could allow a
firmware to have a high speed mode where some processing output is disabled.
When creating designs with parallel branches, it is possible to have a branch with faulty synchronization which would block its input, and results in all
branches being blocked. To debug this situation, it may be helpful to add a BranchEnable function in front of each branch to identify which branch is
causing the blockage.

Demo/Example Usage
JPEG RBG

Sapera APF Programmer's Manual

Sapera APF Reference 217

StreamControl::BranchSync
Synchronizes image streams.

I/O Properties
Latency Type

Variable

Inputs

In [0 63], data input

Outputs

Out [0 63], data output

Parameters
SyncMode

Specifies the mode of operation:

In SyncToMin mode the function will synchronize all input images to the smallest image, that is, cutting larger images.
In SyncToMax mode the function will expand all smaller images to the largest image.
Run-time
changeable

No

Default

SyncToMin

Range

SyncToMin, SyncToMax

Description
The BranchSync performs time and shape synchronization of the input streams. This ensures that pixels from separate inputs are aligned with each other at the
output, and therefore can be correctly processed together. A BranchSync function is required when parallel paths must be combined together as separate inputs
to the same function, and those paths either have different sources, or go through variable-latency functions. See the Synchronization of parallel branches
section for additional information.
To set the number of inputs and outputs, select the input link and specify the required value in the Properties dialog.

Alternatively, you can select the output link and specify the required value in the Properties dialog.

The data on the output links behave completely identically in time and have the same shape. In the case of mixed domain synchronization, such as Image with
Line and Pixel streams, the function converts the output links to the highest input domain, that is, when using a BranchSync to synchronize an Imagelink with a
Line link, both output links will be in Image format. When using the function to synchronize aLine stream and a Pixel stream, all output links will be in the Line
format.
Time synchronization
During transmission of the pixels, pauses can occur due to the flow control or the link bandwidth exceeding the bandwidth of the image source. This figure
shows how the time synchronization is performed for 2 links. Both input links have different timing behavior. However the output links perform identically.

Shape synchronization
Shape synchronization guarantees all images on the output are of the same shape. The BranchSync function supports 2 synchronization modes: synchronization
to the smallest image (SyncToMin) and synchronization to the largest image (SyncToMax).
These modes are selectable by the parameter SyncMode. The SyncToMin mode cuts large images to fit into the smallest one. The SyncToMax mode expands
small images to fit into the largest one. Any missing pixels are replaced by dummy zero pixels.

Sapera APF Programmer's Manual

Sapera APF Reference 218

To set the SyncMode, select the BranchSync function and specify the required value in the Properties dialog.

Using these 2 modes and the 3 different image domains, the following base synchronization combinations are possible:
Image to Image SyncToMin
SyncToMin synchronization for Images streams can be expressed as a Shape-AND function. That is, for a pixel to be included in the output images, it must be
present in both images at the input.
Image to Image SyncToMax
SyncToMax synchronization for Image streamcan be expressed as a Shape-OR function. That is, for a pixel to be included in the output images, it must be
present in at least one, or both, of the input images. The padding pixels are zero pixels.
Line to Line SyncToMin
SyncToMin synchronization for Line streams can be expressed as a Shape-AND function in the X direction. That is, for a pixel to be included in the output
images, it must be present in both images at the input.
Line to Line SyncToMax
SyncToMax synchronization for Line streams can be expressed as a Shape-OR function in X direction. That is, for a pixel to be included in the output images, it
must be present in at least one, or both, of the input images. The padding pixels are zero pixels.
Pixel to Pixel SyncToMin / SyncToMax
Synchronization between Pixel images is a pure time synchronization, since Pixel streams have no shape.
Image to Line SyncToMin
SyncToMin synchronization for Image stream and Line stream can be expressed as a Shape-AND function in X direction. That is, for a pixel to be included in
the output images, it must be present in both images at the input. For an Image to pass through the BranchSync completely the Line link must provide at least
the same amount of lines as the Image contains. Lines exceeding the height of the Image will participate in the synchronization of the next Image and are not
passed through the BranchSync until the next Image arrives at the input link.
Image to Line SyncToMax
SyncToMax synchronization for Image stream and Line stream can be expressed as a Shape-OR function in X direction. That is, for a pixel to be included in the
output images, it must be present in at least one, or both, of the input images. The padding pixels are zero pixels. On the vertical axis, the behavior is the same
as in the Image to Line SyncToMin scenario.
Image to Pixel SyncToMin / SyncToMax
Since Pixel streams have no shape, the Image to Pixel synchronization is a simple bypass of both links. The BranchSync function still performs a time
synchronization, that is, for an Image containing N pixels to pass completely through the BranchSync function, N pixels must be provided by the Pixel link. The
SyncToMin and SyncToMax operation modes are identical.

Sapera APF Programmer's Manual

Sapera APF Reference 219

Line to Pixel SyncToMin /SyncToMax

Since Pixel streams have no shape, the Line to Pixel synchronization is a simple bypass of both links. The BranchSync function still performs time
synchronization, that is, for a Line containing M pixels to pass completely through the BranchSync function, M pixels must be provided by the Pixel link. The
SyncToMin and SyncToMax operation modes are identical.

Demo/Example Usage
Auto Gain, Flat Line Correction, Frame Diff, Recursive Average, Sync Variable Latency

Sapera APF Programmer's Manual

Sapera APF Reference 220

StreamControl::FrameAppend
Vertically concatenates N consecutive input images into a single taller output image.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
ApppendNumber

Number of images at input link In mounted into a single line at output link Out.
Run-time
changeable

Yes

Default

1024

Range

1.. log2(MaxFrameHeight at Out)

Description
The FrameAppend function vertically appends images appearing at the input link In into a larger output image Out. The number of images assembled at the
output link Out is defined by the parameter AppendNumber. For example, when AppendNumber is set to 2, the function will assemble 2 consecutive images into
a new larger one.
Note that the function reduces the frame rate on its output by keeping the original bandwidth. The frame rate is reduced by the factor AppendNumber.
The maximum output image height can be set by selecting the Out link and setting the values of MaxFrameHeight. This maximum image height at the output
influences the maximum possible value of AppendNumber parameter. The correlation follows this formula:
maxAppendNumberValue = log2 (maximum image height at Out).
When changing the AppendNumber value dynamically while aquisition is running, the function guarantees image integrity. The function keeps the old
AppendNumber value until the output frame is finished. After the completion of the current output frame the function will start using the new AppendNumber
value for further merging.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 221

StreamControl::FrameInsert
Performs conditional time-division multiplexing of multiple images into a single output link.

I/O Properties
Latency Type

Variable

Inputs

In [0 63], data input

Ins [0 63], control signal

Outputs

Out, data output

Description
The FrameInsert function conditionally outputs frames from a number of n input links In[0] .. In[n-1] into the output link as consecutive frames. The link Ins[k]
controls if the image at input link In[k] is transmitted or ignored. Depending on the state of the control signal at Ins[0] .. Ins[n-1], up to n images are assembled
into an image sequence at the output link. Thus, if Ins == 1 for all links the resulting frame rate at the output link is n times higher than the frame rate at In.
To set the number of inputs and control links, select the input link and specify the required values in the Properties dialog. The number of In and Ins ports
should be set to the same value.

The binary image control link Ins[k] provided with each image controls the insertion of the correspondent image In[k]. If Ins[k] == 1 for the first pixel (x,y
coordinates = 0,0), the image at In[k] is inserted, otherwise it is skipped. Only the very first pixel of Ins[k] is used for this decision; the state at all other
coordinates is not used.
The insertion order is determined by the image index. For example, the image on input link In[0] will be inserted before the image on input link In[1].
All images at In[k] can be of different height and width (the maximum width and height of the links however must match the maximum width and height of the
input link In[0]). Any two images, In[p] and In[m], need not be synchronized and can be sourced from different functions. The input links In[k] and Ins[k] have
to be synchronized by a StreamControl::BranchSync function.
Although there are no restrictions in image dimensions, the frame rate must be equal for all n input links In[k].
Furthermore, the function expects images to be present on the correspondent input links cyclically, that is, the image on link 2 can be processed once images on
link 0 and 1 are processed. The frame rate of each particular link must be equal. It is not possible for the function to operate normally when one of the input
links provides images at different frame rate as the other links.

Demo/Example Usage
Not available

StreamControl::FrameInsertInitial
Creates an initial image frame for inter-frame processing.

I/O Properties
Latency Type

Variable

Inputs

Org, initial data input

Rec, received data input

Outputs

Out, data output

Sapera APF Programmer's Manual

Sapera APF Reference 222

Parameters
Org Format

Rec Format

NumInitialImg

ConstantPixel

Constant

Expected pixel format for the Org input

Run-time
changeable

No

Default

gray8x8x2

Range

gray8x8x2, gray16x4x2, rgb24x2x2

Expected pixel format for the Rec input

Run-time
changeable

No

Default

gray8x8x2

Range

gray8x8x2, gray16x4x2, rgb24x2x2

Sets the number of initial images to create.

Run-time
changeable

Yes

Default

gray8x8x2

Range

gray8x8x2, gray16x4x2, rgb24x2x2

Enables the use of a constant pixel value for the initial image
Run-time
changeable

Yes

Default

Range

0, 1 [False, True]

Sets the constant pixel value to use for the initial image
Run-time
changeable

Yes

Default

Range

0 - 4294967295

Description
The FrameInsertInitial function is used when the processing uses the current and one or more previous frames. In this case, when the FPGA receives a 1st
frame, it has not yet received a previous frame, therefore the FrameInsertInitial supplies this artificial previous image.
The Rec input will be paused for a number a frames set by the NumInitialImg parameter, which implies that frames on this input must be buffered to external
memory, for example, using the Memory::FrameBuffer function. While the Rec input is paused, the FrameInsertInitial function outputs images with same
dimensions as the images supplied to the Org input. The function either outputs initial frames with constant value (when ConstantPixel=1) or outputs the same
image as those received at the Org input.
Note that for multi-component formats like RGB, the Constant value is defined as a single value for the pixel not the component. For example, with an RGB 8bit input link, and the constant value set to 11862494 (0xB501DE), the output components will be set to the following const values: R = 222 (0xDE), G = 01
(0x01) and B = 181 (0xB5).

Demo/Example Usage
Frame Diff, Recursive Average

StreamControl::FrameMux
Selects an image between between multiple input links.

I/O Properties
Sapera APF Programmer's Manual

Sapera APF Reference 223

Latency Type

Variable

Inputs

In [0 63], data input

Ins [0 63], control signal

Outputs

Out, data output

Parameters
SelectSource

Selects the specified port and passes it to the output.

Run-time
changeable

InfiniteSource

Yes

Default

Range

0, (amount of input links-1)

Activates support for dropping lines when there is a buffer overflow.

Run-time
changeable

No

Default

Disabled

Range

Enabled, Disabled

Description
The FrameMux function provides a switch between different sources. It can be used to select between alternative processing implementations. For example, to
select between different camera ports or select different DMA inputs.
To set the number of inputs, select the input link and specify the required value in the Properties dialog.

The selection is controlled by the parameter SelectSource. The switching between input ports keeps the granularity of the currently transmitted frame and line,
that is, the currently transmitted frame will be transmitted until completed before switching to the new port.
The function acts like a StreamControl::Trash function for all non-selected links.
Note that all input links must be the same format, though different maximum image widths and heights are permitted.
The parameter InfiniteSource should be set to DISABLED except in particular cases where its input is connected to a function that cannot handle flow control
signals. When InfiniteSource is set to ENABLED, the FrameMux function will start dropping lines instead of instructing its input link to stop accepting data.

Demo/Example Usage
ExtractKernel, Sobel Edge

Sapera APF Programmer's Manual

Sapera APF Reference 224

StreamControl::FrameRemoveCond
Enables or disables the flow of images through the function, based on an input value.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Rem, remove control signal

Outputs

Out, data output

Description
The FrameRemoveCond function suppresses whole frames if the input link Rem is '1' at the first pixel of an image at the input link, otherwise the image
becomes available at the output. The FrameRemoveCond function is similar to the BranchEnable function; while the BranchEnable function uses a software
parameter to determine if a given frame is to be output or not, the FrameRemoveCond uses a function input. This allows for the decision to be made quickly on
the FPGA, ba2ed on previous processing results or conditions.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 225

StreamControl::FrameSplit
Separates input images into consecutive output images of height N.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Parameters
ImageHeight

Maximum number of lines of the output image.

Run-time
changeable

Yes

Default

1024

Range

1 - largest power of 2 thats smaller than the MaxFrameHeight of the output link

Description
The FrameSplit function splits the input image into a number of smaller images. The image height of the smaller images is specified by the parameter
ImageHeight. For example, setting ImageHeight to 512 when input image has of 1024 lines will result in 2 new smaller images each having 512 lines.
When the height of the input image is not divisible by the ImageHeight parameter value, the input image will be split into images of the specified height as far
as possible and the last resulting image will be of smaller height, consisting of the remaining lines. Fo example, if the input image has 1024 lines and
ImageHeight is 400, the function will output 2 images with 400 lines and a 3rd image with 224 lines.
Note that the function increases the frame rate but keeps the original bandwidth.
When changing the ImageHeight value dynamically while aquisition is running, the function guarantees image integrity. The function keeps the old
ImageHeight value until the output frame is finished. After the completion of the current output frame the function will start using the new ImageHeight value
for further splitting.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 226

StreamControl::LineAppend
Horizontally appends N lines into a single wider output line.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
AppendNumber

Number of lines at In mounted into a single line at the output.

Run-time
changeable

Yes

Default

1024

Range

0- log2(MaxFrameHeight at the output link)

Description
The LineAppend function appends (concatenates) image lines from the input image, at the input link In, into a larger line at the output link Out. The number of
lines merged into a new line is defined by the parameter AppendNumber, for example, when AppendNumber is set to 2, the function will assemble 2 consecutive
lines from the input image into a new larger line in the output image. When the input image height is not divisible by the AppendNumber parameter value, the
last line in the output image will be shorter and contain the remaining last lines of the input image concatenated together.
Note that the function does not change the frame rate nor the original bandwidth.
When changing the AppendNumber value dynamically while aquisition is running, the function guarantees line integrity. The function keeps the old
AppendNumber value until the output line is finished. After the completion of the current output line the function will start using the new AppendNumber value
for further merging.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 227

StreamControl::LineCarry
Expands the last line of an image into the next image.

I/O Properties
Latency Type

Fixed

Inputs

In, data input2

Outputs

Out, data output

Parameters
Init

Specifies the initial value for the first line or frame at the output link.
Run-time
changeable

Yes

Default

Range

valid range defined by the input link

Description
The LineCarry function fetches the last line in each image appearing at the input link . In the following frame this captured line is now copied into every image
line at the output link.
Note that the behaviour of this function will only affect the following frame and not the current frame. For this reason the output for the first frame must be
specified by the parameter Init.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 228

StreamControl::LineInsert
Performs conditional time-division multiplexing of multiple lines into a single output link.

I/O Properties
Latency Type

Variable

Inputs

In [0 63], data input

Ins [0 63], control signal

Outputs

Out, data output

Description
The LineInsert function multiplexes a number of n input links In[0] .. In[n-1] into the output link. The control link Ins[k] controls if image lines at input link I[k]
are transmitted or ignored. Depending on the state at Ins[0] .. Ins[n-1], the resulting image at the output link may have up to n times more lines than the images
at any the input link.
To set the number of inputs and control links, select the input link and specify the required value in the Properties dialog.

The binary image Ins[k] provided with each image controls the insertion of lines from image I[k]. If Ins[k] == 1 for the first pixel in a line (coordinate x==0,
any y) the current line at In[k] is inserted, otherwise it is skipped. Only the very first pixel per line of Ins[k] is used for this decision, the state at all other xcoordinates is not used.
The insertion order is determined by the image index, that is, the image on In[0] will be inserted before the images on In[1..n-1] and so on.
All images at In[k] must have the same height, but may have different widths (the maximum width of the links however must match the maximum width of the
input link In[0]). Any two images In[p] and In[m] need not be synchronized and can be sourced from different functions. The input links In[k] and Ins[k] have
to be synchronized by a StreamControl::BranchSync function.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 229

StreamControl::LineRemoveCond
Enables or disables the flow of lines through the function, based on an input value.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Rem, remove control signal2

Outputs

Out, data output

Description
The LineRemoveCond function will remove or transmit image lines depending on the binary control input Rem. If the 1st pixel in the line at the Rem input is
1, the corresponding line at the In input will not be output. Otherwise the line at the In input will be copied to the output link.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 230

StreamControl::LineSplit
Separates input lines into consecutive lines of width N.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
LineLength

Sets the line width to use to split the input line to create multiple shorter output lines
Run-time
changeable

Yes

Default

1024

Range

1 - largest power of 2 that is smaller than the MaxFrameWidth of the output link

Description
The LineSplit function splits the input lines into a number of shorter lines. The line width of the shorter lines is specified by the parameter LineLength. For
example, when an input line contains 1024 pixels, setting LineLength to 512, will result in 2 new shorter lines of 512 pixels each.
When the length of the input line is not divisible by the LineLength parameter value, the input line will be split into lines of the specified length as far as
possible and the last resulting line will be of shorter length, comprising the remaining pixels. For example, when the input line contains 1024 pixels and
LineLength is 400, the function will output 2 lines with 400 pixels each and a last 3rd line 224 pixels.
When the value of LineLength is changed dynamically during image acquisition, the function will keep the old LineLength value internally until the currently
processed line is provided at the output link. After the line is completed, the next split will be use the new LineLength value.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 231

StreamControl::Parallelize
Increases the value of PixelsPerClock.

I/O Properties
Latency Type

Variable

Inputs

In, image

Outputs

Out, data output

Description
The function Parallelize increases the parallelism of simultaneously transmitted pixels. That is, it increases the number of pixels per clock at the input link to the
output link, by taking consecutive input pixels and outputting them simultaneously.
To set the new value of PixelsPerClock, select the output link and specify the required value in the Properties dialog.

Demo/Example Usage
Auto Gain, ColorSegment, Simple Buffer DDR, Simple Buffer RLDRAM

Sapera APF Programmer's Manual

Sapera APF Reference 232

StreamControl::PixelCarry
Expands the last pixel of a line or an image into the next line or image.
I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

Out, data output

Parameters
Init

AutoSync

Specifies the value at the output link for the first line or frame.
Run-time
changeable

Yes

Default

Range

valid range defined by the input link I

Specifies the mode of operation:

EoL (End of Line): synchronized to the last pixel in each image line,
EoF (End of Frame): to the last pixel of each frame.
Run-time
changeable

Yes

Default

EoL

Range

EoL, EoF

Description
The PixelCarry function fetches the last pixel of an image appearing at the input link. This value is now kept constant over a certain period and output on Out.
The function works in two modes:

EoL (End-of-Line): for each line the last pixel value in a line is stored and kept constant for the next line.

EoF (End-of-Frame): for each frame the last pixel in the image is stored and kept constant during the next frame.
Note that the behaviour of this function will only affect the following line (or frame) and not the current line (or frame). For this reason the output for the first
line (or frame) must be specified by the parameter Init.

Demo/Example Usage
Auto Gain, Auto-Threshold

Sapera APF Programmer's Manual

Sapera APF Reference 233

StreamControl::PixelCarryEOF
Expands the last pixel of an image into a new image.

I/O Properties
Latency Type

Variable

Inputs

In, input image

Outputs

Out, output image

Parameters
I Format

O Format

Expected pixel format at the input

Run-time
changeable

No

Default

gray8x8

Range

gray8x8, gray16x4, rgb24x2

Target pixel format at the output. Should be set to the same value as I Format.
Run-time
changeable

No

Default

gray8x8

Range

gray8x8, gray16x4, rgb24x2

Description
The PixelCarryEOF function fetches the last pixel of an image appearing at the input link, then generates a new image where all pixels take this value. The
dimensions of the output image are the same as those of the received input image.
The CarryPixelEOF function is similar to the StreamControl::PixelCarry function. PixelCarry replaces the next frame with the last input pixels value found in
the input frame, while PixelCarryEOF outputs the same image immediately.

Demo/Example Usage
Not available

Sapera APF Programmer's Manual

Sapera APF Reference 234

StreamControl::PixelMux
Selects a pixel between between multiple input links.

I/O Properties
Latency Type

Variable

Inputs

In0In1, data input

Outputs

Out, data output

Switch, control signal

Description
For every input pixel, the PixelMux function uses its Switch input to determine which of the In inputs transmits its pixel to the
output.
To set the number of inputs, select the input link and specify the required value in the Properties dialog.

The BitWidth of the Switch input must be equal to log2(number of In inputs), rounded up.
All input links must be synchronized.

Demo/Example Usage
Median Pixel Replacement

Sapera APF Programmer's Manual

Sapera APF Reference 235

StreamControl::PixelRemoveCond
Enables or disables the flow of pixels through the function, based on an input value.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Rem, control signal

Outputs

Out, data output

Parameters
FlushCondition

Controls the insertion of dummy pixels at the end of lines and at the end of the frame.
Run-time
changeable

No

Default

EoL

Range

EoL, EoF (End of Line, End of Frame)

Description
The PixelRemoveCond function removes or passes pixels according to the control input link Rem.
The binary control link Rem determines if a pixel is sent or removed; if Rem = 0, the pixel is sent to the output, otherwise Rem = 1 and the pixel is removed and
is not output.
Due to the removal of pixels, it is possible to construct lines with a width not divisible by the PixelsPerClock of the output link. In such cases the line is filled
with dummy pixels until the line length is divisible by the links PixelsPerClock.
When a complete line is removed the function outputs an empty line of length 0. When all frame pixels are removed, the function outputs an empty frame
consisting of the frame height with empty lines of length 0.
The parameter FlushCondition controls insertion of dummy pixels at the end of each line or frame.
When set to EoL (End of Line), the insertion of dummy pixels occurs at the end of each line when the resulting line length is not divisible by the parallelism.
When set to EoF (End of Frame), the insertion occurs only at the last line at the end of the frame. All previous lines end at parallelism boundaries and the
remaining exceeding pixels are transfered into the following line. This mode is often used for compression applications.
For better readability all dummy pixels are replaced by zero pixels in the simulation. However the function does not set them to zero during runtime. The
dummy pixels contain non- predictable random values.

Demo/Example Usage
Not available

StreamControl::PixelSync
Formats a pixel stream into images.

I/O Properties
Latency Type

Variable

Inputs

In, pixel data stream input

Sample, image data input

Outputs

Out, image data output

Sapera APF Programmer's Manual

Sapera APF Reference 236

Description
The PixelSync function synchronizes a Pixel stream arriving at input link In with a Line or Frame streamat the input link Sample. The output images at the
output link can be seen as a combination of the input links In and Sample. While the output link follows the input Sample in timing and framerate, the data
content is copied from the input link In.
When the data at link In is not valid, that is, the stream on In introduces pauses, and valid data arrives at the input link Sample, the output link will provide the
last valid data from link In until new valid data arrives at link In.

Demo/Example Usage
Signal To Pixel

StreamControl::RectangleReshape
Formats variable width input images into a fixed rectangular size.

I/O Properties
Latency Type

Variable

Inputs

In, data input

Outputs

Out, data output

Parameters
I Format

Sets the expected pixel format for the image input

Run-time changeable

O Format

Default

gray8x8

Range

gray8x8, gray16x4, rgb24x2

Sets the format for the image output, should be set to the same value as I Format.
Run-time changeable

Width

WrapLine

No

Default

gray8x8x2

Range

gray8x8x2, gray16x4, rgb24x2

Sets the output image width

Run-time changeable

MaxHeight

No

No

Default

Range

0 -65535

Sets the maximum output image height.

Run-time changeable

No

Default

Range

0 -65535

Enables the wrapping around of lines that are wider than the specified output Width. When set to true, longer lines are wrapped, or
continued, to the next line. For example, JPEG compression can generate one very wide line, in this case the long input line can be split
onto multiple output lines. The host will then receive the JPEG data stream as an image, but the image contents can be interpreted as a

Sapera APF Programmer's Manual

Sapera APF Reference 237

JPEG stream and not as pixel values.

Run-time changeable

No

Default

Range

0 -65535

Description
Formats variable width input images into a fixed rectangular size. The RectangleReshape function is required for handling
variable width input images since the PCIe DMA must be supplied with images that have fixed width.

Demo/Example Usage
Variable Output Dimensions

StreamControl::Serialize
Decreases the value of PixelsPerClock.

I/O Properties
Latency Type

Variable

Inputs

In, image

Outputs

Out, data output

Description
The Serialize function decreases the value of PixelsPerClock. Decreasing the value of PixelsPerClock has the effect of reducing the maximum bandwidth, but
also reduces the FPGA resource usage.To set the number of pixels per clock, select the output link and specify the required value in the Properties dialog.

Demo/Example Usage
Auto Gain, Bayer, ColorSegment

Sapera APF Programmer's Manual

Sapera APF Reference 238

StreamControl::Trash
Provides a data sink for unused links.

I/O Properties
Latency Type

Fixed

Inputs

In, data input

Outputs

None

Description
The Trash function is a data sink for unused links.
If functions generate output links that are not needed in a particular design, or during the development cycle some paths are not implemented yet, it is necessary
to terminate floating output links. Connecting floating outputs to the input of a Trash function terminates these outputs and satisfies the design rule check.

Demo/Example Usage
Auto Gain

Sapera APF Programmer's Manual

Sapera APF Reference 239

Appendix: Installation and

Licensing
System Requirements
Sapera APF runs under either 32-bit or 64-bit version of Windows.
Minimum system hardware requirements:
4 GB of RAM
25 GB free space on hard drive
A high performance CPU is recommended; the recent Xilinx ISE tools (version 13 and above) can run faster on multi-core CPUs.

Installation
There are 2 methods available to install the Sapera APF SDK:

Use a Teledyne DALSA Sapera APF Software CD: Click the Software Installation option on the installation splash
screen and follow the instructions. You can also choose to install drivers for Teledyne DALSA products such as cameras
and frame grabbers. The Teledyne DALSA Sapera APF Software CDs also contains documentation such as data sheets
and user manuals for Teledyne DALSA products.

Download the latest Sapera APF SDK from the Teledyne DALSA website:
http://www.teledynedalsa.com/mv/products/software.aspx: Run the self-extracting installation program
SaperaProSDK_7.x.x.xxx.exe and follow the instructions.
The Teledyne DALSA website contains Sapera Vision Software updates for registered users. Check
http://www.teledynedalsa.com/mv/products/software.aspx: for the latest versions of the Sapera APF SDK and Runtime installations
available for download.

Sapera APF Programmer's Manual

Appendix: Installation and Licensing 241

Additional Installation Requirements

In addition, Sapera APF requires the installation of Xilinx ISE (Logic Edition), 10.1 or later, which can be downloaded directly
from the Xilinx website (http://www.xilinx.com/support/download/index.htm).
When installing the Xilinx ISE, select the ISE Design Suite: Logic Edition. For the complete installation procedure, refer to to the
Sapera APF Quick Start Guide document included with the Sapera APF installation
The Xilinx software must be installed on the same PC as the Sapera APF development tool is installed. Sapera APF automatically
detects the existence of the installed Xilinx tool. The Xilinx tool is used whenever you start a synthesize process within Sapera
APF.
To deploy Sapera APF designs, the target hardware, a X64 Xcelera VX4 frame grabber must be installed. For design purposes
only, target hardware is not required on the host system.

Licensing
Sapera APF is protected software; therefore a license is required. Please refer to the following sections for a general description
of the Sapera APF licensing system and how to generate and install your license.

What is a license?
Two items are required to enable the Sapera APF license on a given computer:
-

A protection dongle (device plugged into one of the computers USB ports)

A license file (.LIC)

A Sapera APF license file is supplied at the time of purchase by email (to the address supplied in the purchase) and includes the
following information:

The list products enabled by this license file. License files for Sapera APF enable all Sapera Processing tools
available at the time of release.

The serial number of the protection dongle, which implies that the license file is valid only when used with a
specific protection dongle

The date specifying the end of maintenance contract (one year after generating the license). For instance if you
generated your license on August 2012 you can operate any Sapera APF version whose release date is prior to
August 2013.

Sapera APF Programmer's Manual

Appendix: Installation and Licensing 242

Installing a License
For Windows installations, you install your license using the License Manager program. The License Manager program can be
found under the Windows Start menu, under Teledyne DALSA Sapera License Manager. The following steps must be repeated
for each computer where Sapera APF is installed (note that the USB protection dongle must be connected for Sapera APF to
function correctly):

Start the License Manager program

Click the Load Single License button

Select the license file from your disk (<your serial number>.lic)

This action searches for a correspondence between a protection device present in your system and the selected license file. If any
match is found the license is activated and the state of each of option in the license is updated with License OK (as shown
below). In this case your license is ready to use, otherwise refer to the section Licensing Errors for more information on possible
issues.

Alternatively, you can install multiple licenses all at once by clicking Load Multiple Licenses. In this case, instead of selecting a
file you select a directory which contains a list of license files. Then each license file that matches a device in the system is
activated. The results are listed in the diagnostic window.
Note that if the USB dongle is moved to a different computer (where Sapera APF was also installed), the License
Manager must be run on this computer as well to initialize its local license. Therefore, it is important to retain the
.LIC file that is sent by email upon purchase of Sapera APF.

Licensing Errors
This section describes the possible errors that can occur in the Sapera APF licensing system while providing hints on how to
troubleshoot these problems.
1. A license cannot be found
The License Manager displays the state License not found as below.

Sapera APF Programmer's Manual

Appendix: Installation and Licensing 243

This could simply mean that you have not installed a license. In this case refer to the section Installing a License. Otherwise this
symptom can occur in different scenarios. Click the Show License button to determine which situation applies. Refer to the table
below.
Problem

How to Determine

Solution

Device not detected

A tab with your device serial number

cannot be found

Check that the device (dongle, camera or frame-grabber) is properly installed.

For a frame-grabber also make sure the driver is installed and working.
For a dongle the Sentinel driver is automatically installed by Sapera APF. However
you may verify that this driver is running.
Note: if you suspect that the driver is not running you may relaunch the driver
installation by running the executable from the Sentinel directory of the Sapera
APF installer.
For a parallel dongle make certain the parallel port setting in your systems BIOS is
either Normal, ECP, or Bi-directional. EPP mode is not supported.

Device not
programmed

A tab with your device serial number is

present but displays No License

You need to program your device. See the Installing a License section.

Device not active

A tab with your device serial number is

present but displays Not Active

The license is currently active on another device. Select the required device from the
Activation box.

2.

The license is too old

The License Manager displays the state License too old as below.

Sapera APF Programmer's Manual

Appendix: Installation and Licensing 244

This error specifies that your maintenance contract has expired. This means the currently installed license covers a period that
does not include the release date of the current Sapera APF version. This error usually happens when you install a new version of
Sapera APF which is too recent with respect to your current license. It can also happen if you installed an older license on the
current Sapera APF version.
3.

The license cannot be programmed.

If the protection device is detected the license programming would fail if the serial number contained in the license file does not
correspond to that of the current device. The picture below shows the corresponding error message.

In fact the License Manager fails to locate the required device (that is, the one whose serial number is specified in the license).
You can view the device serial number using the Show Licenses button. You can also check the content of your license file by
selecting the View | Show License File Content menu item.
4.

Runtime Errors

After your license has been properly installed you should be ready to use Sapera APF. However some errors (not seen in License
Manager) may occur when running your application.

A license for a specific tool is not found. For example, you are trying to run an application that uses the barcode
tool but your license does not contain the barcode option.

A development license is not found. If you are running your application in debug mode a development license is
absolutely required. You will get this error if your license does not include the development option.

Sapera APF Programmer's Manual

Appendix: Installation and Licensing 245

Contact Information
Sales Information
Visit our web site:

www.teledynedalsa.com/mv

Email:

mailto:[email protected]

Canada
Teledyne DALSA Montreal office
7075 Place Robert-Joncas, Suite #142
St. Laurent, Quebec, Canada
H4M 2Z2
Tel:
(514) 333-1301
Fax:
(514) 333-1388

Asia Sales
Teledyne DALSA Asia Pacific
Ikebukuro East 13F
3-4-3 Higashi Ikebukuro,
Toshima-ku, Tokyo
Japan
Tel:
+81 3 5960 6353
Fax:
+81 3 5960 6354

Sapera APF Programmer's Manual

USA Sales
Teledyne DALSA Billerica office
700 Technology Park Drive
Billerica, Ma.
01821
Tel:
(978) 670-2000
Fax:
(978) 670-2010

European Sales
Teledyne DALSA Europe
Breslauer Str. 34
D-82194 Grbenzell (Munich)
Germany
Tel: +49 - 8142 46770
Fax: +49 - 8142 - 467746

Contact Information 247

Technical Support
Any support question or request can be submitted via our web site:
Technical support form via our web page:
Support requests for imaging product installations,
Support requests for imaging applications

http://www.teledynedalsa.com/mv/support

Product literature and driver updates

http://www.teledynedalsa.com/mv/download

Sapera APF Programmer's Manual

Contact Information 248

Glossary of Terms
Blob

A group of connected image pixels representing a region (or object) of an image. Blobs are created by an image processing
algorithm that tries to connect together neighboring pixels that have a nearly similar brightness.
Driver

Also called a device driver, a program routine that links a peripheral device to the operating system. Specific to the Bandit-II, its
VGA driver is required for its display adapter functionality and a device driver is required for its frame grabber capabilities.
Frame

Synonym for the word image.

Grayscale

In image processing, the range of available brightness levels, displayed in shades of gray. In an 8-bit system, the grayscale
contains values from 0 to 255.
Latency

Time in clock cycles that it takes for a specific block of data to work its way through a function
Lookup Table, LUT

In image processing, the segment of memory that stores values for point processes. Input pixel values are those of the original
image, while output values are those altered by the chosen point process. An input lookup table destructively modifies the stored
image data, whereas the output lookup table simply receives the stored data and modifies it for output only.
Low Pass Filter

A filter that blocks high frequencies and allows lower frequencies to pass through. Used to limit undesirable analog information
(such as high frequency video noise) before converting to digital data.
LSB

Least Significant Bit in a binary data word.

LUT

(Look Up Table) In image processing, the memory that stores the values for point processes. Input pixel values are those from the
original image, while output values are those displayed on the monitor as altered by the chosen point process.
MSB

Most Significant Bit in a binary data word.

Pixel

A single picture element, the smallest individual digital video component. The number of pixels describes the number of digital
samples taken of the analog video signal. The number of pixels per video line by the number of active video lines describes the
acquisition image resolution. The binary size of each pixel (i.e., 8 bits, 15 bits, 24 bits) defines the number of gray levels or colors
possible for each pixel.
ROI Region-of-Interest

A rectangular segment of an image that delimits the portion of the image to be processed.

Sapera APF Programmer's Manual

Glossary of Terms 249

Index

example designs, 77
expiry date, 242

G
B
Boolean
BitwiseAnd, 107
BitwiseNot, 108
BitwiseOr, 108
BitwiseXNor, 109
BitwiseXor, 110
Equal, 111
EqualVal, 111
GreaterOrEqual, 112
GreaterOrEqualVal, 112
GreaterThanVal, 113
InRange, 114
LessOrEqual, 115
LessOrEqualVal, 115
LessThan, 116
LessThanVal, 116
NotEqual, 117
NotEqualVal, 117
Boolean Functions, 106

C
CHM, ii
Color
BayerToRGB, 119
BayerToRGB_5X5, 120
ChannelMerge, 121
ChannelSelect, 122
ChannelSplit, 123
ColorMatrix_3x3, 124
HSItoRGB, 125
RGBtoHSI, 126
RGBtoYUV, 127
WhiteBalance, 128
YUVtoRGB, 129
Color Functions, 118

D
DataReduction
Huffman9bit4P, 130
JPEGColor4P4k, 131
Paeth8bit4P8k P, 132
RLE8P, 132
DataReduction Functions, 130
Directives
PixelBuffer, 135
ReinterpretColor, 136
ReinterpretMaxDimension, 136
ReinterpretPixelsPerClock, 137
ReinterpretSign, 137
Directives Functions, 135

Sapera APF Programmer's Manual

Geometry
DownSample, 138
UpSample, 139
Geometry Functions, 138

I
Image I/O
CameraIn, 140
FrameCreateBlank, 142
FrameOutRaw, 143
RecursiveIn, 145
RecursiveOut, 146
Image I/O Functions, 140
installing a license, 243
Internet, ii

K
Kernel
BinaryDilate, 148
BinaryErode, 149
Convolution, 150
GrayscaleDilate, 150, 151
HitOrMiss, 151
KernelCreate, 152
KernelExtract, 153
KernelSplit, 154
Median, 155
Kernel Functions, 147

L
License, 242
installing, 243

M
Math
AbsoluteValue, 156
Add, 157
ApplyLUT, 157
Constant, 158
Divide, 159
Multiply, 159
MultiplybyVal, 160
SaturateHigh, 161
SaturateLow, 162
ShiftLeft, 163
ShiftRight, 164
Subtract, 165
Math Functions, 156
Memory
FrameBuffer, 166
LineBuffer, 168
Memory Functions, 166
Index 251

P
password protected, 242
PDF, ii
Pixel Control Functions, 169
PixelControl
BitsExtract, 170
FrameCount, 171
KeepLSB, 171
KeepMSB, 172
ParallelMerge, 173
ParallelMerge, 174
PixelHold, 175
PixelMerge, 176
SelectFromParallel, 177
XPos, 177
YPos, 178

S
Signal I/O
CC1, CC2, CC3, CC4, 180
ClockGenerator, 180
Debounce, 182
Delay, 183
EdgeToShortPulse, 184
FlipFlop, 185
FrameEndPulse, 186
FrameStartPulse, 187
FrameTrigIn0, 186
FrameTrigIn1, 186
FrameTrigOut0, 187
FrameTrigOut1, 187
FreqReduce, 188
Gate, 189
GPI_0, GPI_1, GPI_2, GPI_3, 189
GPO_0, GPO_1, GPO_2, GPO_3, 189
LineEndPulse, 190
LineStartPulse, 190
PeriodToPixel, 191
PhaseDiffToPixel, 192
PixelHighPulse, 193
PixelPeriodToPulse, 193
PixelRead, 194
PixelToSignal, 194
PulseWidthIncrease, 195
PulseWidthLimit, 196
PulseWidthToPixel, 197
SignalHigh, 197
SignalInvertCond, 198
SignalLow, 198
SignalMux, 199
SignalRead, 200
SignalToPixel, 201
SignalWrite, 202
Signal I/O Functions, 179
Statistics
CountModulo, 204
FrameMax, 206
FrameMin, 207
FrameSum, 208
Histogram, 209
HorizontalMax, 210
Sapera APF Programmer's Manual

HorizontalMin, 210
HorizontalSum, 211
PixelCounterNonZero, 212
VerticalMax, 213
VerticalMin, 213
VerticalSum, 214
Statistics Functions, 203
StreamControl
BranchCreate, 216
BranchSync, 218
FrameAppend, 221
FrameInsert, 222
FrameInsertInitial, 222
FrameMux, 223
FrameRemoveCond, 225
FrameSplit, 226
LineAppend, 227
LineCarry, 228
LineRemoveCond, 230
LineSplit, 231
Parallelize, 232
PixelCarry, 233
PixelCarryEOF, 234
PixelMux, 235
PixelRemoveCond, 236
PixelSync, 236
RectangleReshape, 237
Serialize, 238
Trash, 239
TrashCond, 217
StreamControl Functions, 215

W
Web site, ii

Index 252