Main Content

visionhdl.PixelsToFrame

Convert pixel stream to frame-based video

expand all in page

Description

The visionhdl.PixelsToFrame System object™ converts a color or grayscale pixel stream and control structures into frame-based video. The control structure indicates the validity of each pixel and its location in the frame. The pixel stream format can include padding pixels around the active frame. You can configure the frame and padding dimensions by selecting a common video format or by specifying custom dimensions. For details about the pixel stream format, see Streaming Pixel Interface.

Use this object to convert the output of a function targeted for HDL code generation back to frames. The object itself does not support HDL code generation.

If your design converts frames to a pixel stream and later converts the stream back to frames, specify the same video format for the FrameToPixels object and the PixelsToFrame object.

To convert pixel stream to frame-based video:

  1. Create the visionhdl.PixelsToFrame 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

P2F = visionhdl.PixelsToFrame(Name,Value)

Description

P2F = visionhdl.PixelsToFrame(Name,Value) returns a System object that converts a pixel stream to image frames. Set properties using one or more name-value pairs. Enclose each property name in single quotes.

example

Properties

expand all

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.

Number of values used to represent each pixel, specified as 1, 2, 3, or 4 components.

  • For grayscale video, set this property to 1.

  • For color video, for example, {R,G,B} or {Y,Cb,Cr}, set this property to 3.

  • For color video with an alpha channel for transparency, set this property to 4.

The visionhdl.PixelsToFrame object expects a matrix of P-by-NumComponents values, where P is the total number of pixels in the padded frame.

Dependencies

When NumComponents is greater than 1, you must set the NumPixels property to 1.

Number of pixels transferred on the streaming interface for each cycle, specified as 1, 2, 4, or 8. To enable multipixel streaming and increase throughput for high-resolution or high-frame-rate video, set this property to 2, 4, or 8. The visionhdl.PixelsToFrame object expects a P-by-NumPixels matrix, where P is the total number of pixels in the padded frame.

Note

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.

Dependencies

When NumPixels is greater than 1, you must set the NumComponents property to 1.

Dimensions of the active region of a video frame. To select a predefined format, specify the VideoFormat property as one of the options in the first column of the table. For a custom format, set VideoFormat to 'Custom', and specify the dimensional properties as integers.

Video FormatActive Pixels Per LineActive Video Lines
240p320240
480p640480
480pH720480
576p720576
720p1280720
768p1024768
1024p12801024
1080p (default)19201080
1200p16001200
2KCinema20481080
4KUHDTV38402160
8KUHDTV76804320
CustomUser-
defined		User-
defined

Usage

Syntax

[frm,validOut] = P2F(pixels,ctrlIn)

Description

[frm,validOut] = P2F(pixels,ctrlIn) converts a vector of pixel values representing a padded image, pixels, and an associated vector of control structures, ctrlIn, to an image matrix, frm. The control structure indicates the validity of each pixel and its location in the frame. The output image, frm, is valid if validOut is true.

For details about the pixel stream format, see Streaming Pixel Interface.

example

Input Arguments

expand all

Pixel values, specified as a P-by-NumComponents matrix, or P-by-NumPixels matrix, where:

  • P is the total number of pixels in the padded image, which is TotalPixelsPerLine × TotalVideoLines.

  • NumComponents is the number of components used to express a single pixel.

  • NumPixels is the number of pixels transferred on the streaming interface per cycle. When NumPixels is greater than 1, you must set NumComponents to 1.

    Note

    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.

Set the size of the padded image using the VideoFormat property. If the number of elements in pixels does not match the dimensions specified by VideoFormat, the object returns a warning.

Data Types: uint | int | logical | fi | double | single

Control structures associated with the input pixels, specified as a P-by-1 vector. P is the total number of pixels in the padded image, which is TotalPixelsPerLine × TotalVideoLines. Each structure contains five control signals indicating the validity of the pixel and its location in the frame. For multipixel streaming, the control signals apply to each set of NumPixels values. See Pixel Control Structure.

Output Arguments

expand all

Output image, returned as an ActiveVideoLines-by-ActivePixelsPerLine-by-NumComponents matrix, where:

  • ActiveVideoLines is the height of the active image.

  • ActivePixelsPerLine is the width of the active image.

  • NumComponents is the number of components used to express a single pixel.

The data type of the pixels is the same as the input pixels.

Data Types: uint | int | logical | fi | double | single

Frame status, returned as a logical value. When validOut is true, the frame is reassembled and ready for use.

Data Types: logical

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)

expand all

stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

This example uses:

Open Live Script

This example converts a custom-size grayscale image to a pixel stream. It uses the visionhdl.LookupTable object to obtain the negative image. Then it converts the pixel stream back to a full-frame image.

Load the source image from a file. Select a portion of the image matching the desired test size.

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

Figure contains an axes object. The hidden axes object with title Input Image contains an object of type image.

Create a serializer object and specify the size of the 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 (LUT) object to generate the negative of the input image.

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

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

[pixIn,ctrlIn] = frm2pix(frmInput);

Prepare to process pixels by preallocating output vectors.

[~,~,numPixelsPerFrame] = getparamfromfrm2pix(frm2pix);
pixOut = zeros(numPixelsPerFrame,1,'uint8');
ctrlOut = repmat(pixelcontrolstruct,numPixelsPerFrame,1);

For each pixel in the stream, look up the negative of the pixel value.

for p = 1:numPixelsPerFrame  
    [pixOut(p),ctrlOut(p)] = inverter(pixIn(p),ctrlIn(p));
end

Create a deserializer object with a format that matches the format of the serializer. Convert the pixel stream to an image frame by calling the deserializer object. Display the resulting image.

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

Figure contains an axes object. The hidden axes object with title Output Image contains an object of type image.

Version History

Introduced in R2015a

expand all

See Also

|

Topics