Main Content

dsphdl.Downsampler

Downsample by removing data samples between input samples

Since R2022b

expand all in page

Description

The dsphdl.Downsampler System object™ downsamples an input signal by removing K–1 data samples between input samples, where K is the downsampling factor. The System object supports these combinations of input and output data.

  • Scalar input and scalar output

  • Vector input and scalar output

  • Vector input and vector output

The System object provides an architecture suitable for HDL code generation and hardware deployment.

To downsample input data with a downsampler, follow these steps:

  1. Create the dsphdl.Downsampler 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?

Note

You can also generate HDL code for this hardware-optimized algorithm, without creating a MATLAB® script, by using the DSP HDL IP Designer app. The app provides the same interface and configuration options as the System object.

Creation

Syntax

downsample = dsphdl.Downsampler
downsample = dsphdl.Downsampler(Name=Value)

Description

downsample = dsphdl.Downsampler creates an HDL-optimized upsampler System object with default property values.

downsample = dsphdl.Downsampler(Name=Value) sets properties using one or more name-value arguments.

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.

Downsampling factor specified as an integer in the range [1, 2.^16]. This value gives the rate by which the System object decreases the input sampling rate.

Sample offset, specified as an integer in the range [0, DownsampleFactor – 1].

Option to enable the ready output argument, specified as a numeric or logical 1 (true) or 0 (false)

Usage

Syntax

[dataOut,validOut] = downsampler(dataIn,validIn)
[dataOut,validOut] = downsampler(dataIn,validIn,reset)

Description

[dataOut,validOut] = downsampler(dataIn,validIn) downsamples the input dataIn using a downsampling factor only when validIn is true.

[dataOut,validOut] = downsampler(dataIn,validIn,reset) downsamples the input data when reset is false and clears the filter internal states when reset is true. The System object expects the reset argument only when you set the ResetInputPort property to true.

example

Input Arguments

expand all

Input data, specified as a scalar or a column vector with a length up to 64. The input data must be an integer or a fixed-point value with a word length less than or equal to 128.. The DownsampleFactor property must be an integer multiple of the input frame size.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi

Valid input data indicator, specified as a numeric or logical 1 (true) or 0 (false). When validIn is 1 (true), the object captures the values from the dataIn argument. When validIn is 0 (false), the object ignores the values from the dataIn argument.

Data Types: logical

Option to clear the internal states, specified as a numeric or logical 1 (true) or 0 (false). When reset is 1 (true), the object stops the current calculation and clears the internal states. When reset is 0 (false) and valid is 1 (true), the object captures data for processing.

For more reset considerations, see the Reset Signal section on the Hardware Control Signals page.

Dependencies

To enable this argument, set the ResetInputPort property to true.

Data Types: logical

Output Arguments

expand all

Downsampled data, returned as a scalar or a column vector with a length from 1 to 64.

For a vector input, if the vector size is less than or equal to DownsampleFactor, the object outputs scalar output.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi

Valid output data indicator, returned as a logical 0 or 1. A value of 1 indicates that the object returns valid data in the dataOut argument. A value of 0 indicates that values in the dataOut argument are not valid.

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

getLatencyLatency of downsampler
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 Script

This example shows how to use a dsphdl.Downsampler to downsample data. You can generate HDL code for this object.

Generate Frames of Random Input Samples

Set up workspace variables for the object to use. The object supports scalar and vector inputs. For vector inputs, the input data must be a column vector of size 1 to 64 and K must be an integer multiple of the input frame size.

clear variables % Clear workspace
clear HDLDownsample

K = 8;                % Downsample factor
O = 5;                % Sample offset

scalar = true;
if scalar
    vecSize = 1;
    value = 1;
else
    vecSize = 16; %#ok % Vector size must be a multiple or factor of K
    value = vecSize/K;
end

numFrames = 1;
dataSamples = cell(1,numFrames);
framesize = zeros(1,numFrames);
refOutput = [];
WL = 0;               % Word length
FL = 0;               % Fraction length

Generate Reference Output from MATLAB function

Generate frames of random input samples and apply to the downsample function. You can use the output that this function generates as a reference against which to compare the output of the System object.

totalsamples = 0;
for i = 1:numFrames
    framesize(i) = randi([5 200],1,1)*vecSize;
    dataSamples{i} = fi(randn(vecSize,framesize(i)),1,16,8);
    ref_downsample= downsample((dataSamples{i}(:)),K,O);
    refOutput = [refOutput,ref_downsample]; %#ok
end

Run Function Containing System Object

This example uses the HDLDownsample function for scalar and vector inputs. Set the properties of the System object in this function to match the input data properties.

function [dataOut,validOut] = HDLDownsample(dataIn,validIn)
persistent hdlDSObj
if isempty(hdlDSObj)
    hdlDSObj = dsphdl.Downsampler('DownsampleFactor',8,'SampleOffset',5);
end
[dataOut,validOut] = hdlDSObj(dataIn,validIn);
end

Insert the required number of idle cycles after each frame using the latency variable to avoid invalid output data.

latency = 2+O;
dataOut = zeros(value,totalsamples+numFrames*latency);
validOut = zeros(1,totalsamples+numFrames*latency);
idx=0;
for ij = 1:numFrames
    for ii = 1:size(dataSamples{ij},2)
        idx = idx+1;
        [dataOut(:,idx),validOut(idx)] = HDLDownsample( ...
            dataSamples{ij}(:,ii), ...
            true);
    end
    for ii = 1:latency
        idx = idx+1;
        [dataOut(:,idx),validOut(idx)] = HDLDownsample( ...
            fi(zeros(vecSize,1),1,16,8), ...
            false);
    end
end

Compare Function Output with Reference Output

Compare the output of the HDL function with the output of the downsample function.

HDLOutput = dataOut(:,validOut==1);
HDLOutput = HDLOutput(:);

fprintf('\n Downsampler:\n');
difference = (abs(HDLOutput-refOutput(1:length(HDLOutput)))>0);
fprintf(['\nTotal number of samples differed between Behavioral ' ...
    'and HDL simulation: %d \n'],sum(difference));

 Downsampler:

Total number of samples differed between Behavioral and HDL simulation: 0
Open Live Script

The latency of the dsphdl.Downsampler System object™ varies according the downsample factor and the input vector size. Use the getLatency function to find the latency of an downsampler configuration. The latency is the number of cycles between the first valid input and the first valid output, assuming the input is continuously valid.

Create a dsphdl.Downsampler System object and get the latency. The default System object has an downsampling factor of 2 and a sample offset of 0.

downsampler = dsphdl.Downsampler
downsampler = 
  dsphdl.Downsampler with properties:

    DownsampleFactor: 2
        SampleOffset: 0

  Use get to show all properties


V = 1;
downsampler.SampleOffset = 1;
Ydefault = getLatency(downsampler,V)
Ydefault = 
3

Modify the object and check the resulting change in latency.

downsampler.DownsampleFactor = 8;
Y1 = getLatency(downsampler)
Y1 = 
1

Change the vector input size to 2. Check the resulting change in latency.

V = 4;
downsampler.DownsampleFactor = 2;
Vec = getLatency(downsampler,V)
Vec = 
2

Algorithms

expand all

Extended Capabilities

Version History

Introduced in R2022b

See Also

Blocks

Objects