visionhdl.LookupTable

Map input pixel to output pixel using custom rule

Description

The visionhdl.LookupTable System object™ uses a custom one-to-one map to convert between an input pixel value and an output pixel value.

To map an input pixel value to an output pixel value:

1. Create the visionhdl.LookupTable object and set its properties.

2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

LUT = visionhdl.LookupTable(tabledata)

Description

LUT = visionhdl.LookupTable(tabledata) returns a lookup table System object that performs a one-to-one mapping between an input pixel and an output pixel. The mapping is defined by the Table property, which is set to the value of tabledata.

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Table — Map between input pixel and output pixel

uint8(0:1:255) (default) | vector

Map between input pixel and output pixel, specified as a row or column vector of any data type. The data type of the table data determines that of pixelout. This mapping determines the one-to-one correspondence between the input pixelin value and the output pixelout value.

• The length of the table data must equal 2^WordLength, where WordLength is the size, in bits, of pixelin. This object does not perform interpolation. Every input value must have a corresponding output value in the table.

• The smallest representable value of the input data type maps to the first element of the table, the second smallest value maps to the second element, and so on. For example, if pixelin has a data type of fixdt(0,3,1), the input value 0 maps to the first element of the table, 0.5 maps to the second element, 1 maps to the third element, and so on.

Example: uint8(linspace(255,0,256))

Usage

Syntax

[pixelout,ctrlout] = LUT(pixelin,ctrlin)

Description

[pixelout,ctrlout] = LUT(pixelin,ctrlin) returns the pixel value, pixelout, located in the table at the address specified by the input pixel value, pixelin. The object delays the input control signals, ctrlin, to align the output control signals, ctrlout, with the output data.

This object uses a streaming pixel interface with a structure for frame control signals. This interface enables the object to operate independently of image size and format and to connect with other Vision HDL Toolbox™ objects. The object accepts and returns a scalar pixel value and control signals as a structure containing five signals. The control signals indicate the validity of each pixel and its location in the frame. To convert a pixel matrix into a pixel stream and control signals, use the visionhdl.FrameToPixels object. For a description of the interface, see Streaming Pixel Interface.

Input Arguments

pixelin — Input pixel stream

scalar | row vector

Input pixel, specified as a scalar intensity value or a row vector of three values representing one pixel in R'G'B' or Y'CbCr color space. Integer and fixed-point data types larger than 16 bits are not supported. Signed data types are not supported.

You can simulate System objects with a multipixel streaming interface, but you cannot generate HDL code for System objects that use multipixel streams. To generate HDL code for multipixel algorithms, use the equivalent Simulink^® blocks.

Data Types: uint8 | uint16 | fi(0,N,F), N <= 16 | logical

ctrlin — Control signals accompanying input pixel stream

pixelcontrol structure

Control signals accompanying the input pixel stream, specified as a pixelcontrol structure containing five logical data type signals. The signals describe the validity of the pixel and its location in the frame. For more details, see Pixel Control Structure.

Data Types: struct

Output Arguments

pixelout — Output pixel stream

scalar | vector

Output pixel, returned as a scalar intensity value or a vector of three values representing R'G'B' or Y'CbCr color space. The data type of the output is the same as the data type of the entries you specify in the Table property. The dimensions of the output pixel is the same as the dimensions of the input pixel.

The software supports double and single data types for simulation, but not for HDL code generation.

Data Types: uint8 | uint16 | int8 | int16 | fi | logical | double | single

ctrlout — Control signals accompanying output pixel stream

pixelcontrol structure

Control signals accompanying the output pixel stream, returned as a pixelcontrol structure containing five logical data type signals. The signals describe the validity of the pixel and its location in the frame. For more details, see Pixel Control Structure.

Data Types: struct

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Compute Negative Image

Create the negative of an image by looking up the opposite pixel values in a table.

Set dimensions of the test image, and load an image source. Select a portion of the image matching the desired test size.

frmActivePixels = 64;
frmActiveLines = 48;
frmOrig = imread('rice.png');
frmInput = frmOrig(1:frmActiveLines,1:frmActivePixels);
figure
imshow(frmInput,'InitialMagnification',300)
title 'Input Image'

Create a serializer object and define inactive pixel regions.

frm2pix = visionhdl.FrameToPixels( ...
      'NumComponents',1, ...
      'VideoFormat','custom', ...
      'ActivePixelsPerLine',frmActivePixels, ...
      'ActiveVideoLines',frmActiveLines, ...
      'TotalPixelsPerLine',frmActivePixels+10, ...
      'TotalVideoLines',frmActiveLines+10, ...
      'StartingActiveLine',6, ...     
      'FrontPorch',5);

Create a lookup table object. The input pixel data type is uint8, so the negative value is 255-pixel. The output pixel data type is the same as the data type of the table contents.

tabledata = uint8(linspace(255,0,256));
inverter = visionhdl.LookupTable(tabledata);

Serialize the test image. pixIn is a vector of intensity values. ctrlIn is a vector of control signal structures.

[pixIn,ctrlIn] = frm2pix(frmInput);

Initialize the output variables. Then, for each pixel in the padded frame, look up its negative value.

[~,~,numPixelsPerFrame] = getparamfromfrm2pix(frm2pix);
pixOut = zeros(numPixelsPerFrame,1,'uint8');
ctrlOut  = repmat(pixelcontrolstruct,numPixelsPerFrame,1);
for p = 1:numPixelsPerFrame  
    [pixOut(p),ctrlOut(p)] = inverter(pixIn(p),ctrlIn(p));
end

Create deserializer object with a video format matching that of the serializer. Convert the output pixel stream to an image frame, and display the result.

pix2frm = visionhdl.PixelsToFrame( ...
      'NumComponents',1, ...
      'VideoFormat','custom', ...
      'ActivePixelsPerLine',frmActivePixels, ...
      'ActiveVideoLines',frmActiveLines, ...
      'TotalPixelsPerLine',frmActivePixels+10);
[frmOutput,frmValid] = pix2frm(pixOut,ctrlOut);
if frmValid
    figure
    imshow(frmOutput,'InitialMagnification',300)
    title 'Output Image'
end

Algorithms

Latency

The latency of this System object is 2 cycles.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

This System object supports C/C++ code generation for accelerating MATLAB^® simulations, and for DPI component generation. For more information about acceleration, see Accelerate Pixel-Streaming Designs Using MATLAB Coder. For more information about DPI component generation, see Considerations for DPI Component Generation with MATLAB (HDL Verifier).

HDL Code Generation

Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.

To generate HDL code from Vision HDL Toolbox System objects, see Design Hardware-Targeted Image Filters in MATLAB.

Version History

Introduced in R2015a

R2020b: Multipixel streaming

The object now supports multipixel streams. For multipixel streaming, the object supports input and output column vectors of 4 or 8 pixels. The ctrl argument remains scalar, and the control signals in the pixelcontrol structure apply to all pixels in the vector.

You can simulate System objects with a multipixel streaming interface, but you cannot generate HDL code for System objects that use multipixel streams. To generate HDL code for multipixel algorithms, use the equivalent Simulink blocks.