<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NVIDIA 2D Image And Signal Performance Primitives (NPP): Imaging-Processing Specific API Conventions</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">NVIDIA 2D Image And Signal Performance Primitives (NPP)
 <span id="projectnumber">Version 10.1.1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Imaging-Processing Specific API Conventions </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="nppi_naming"></a>
Function Naming</h1>
<p>Image processing related functions use a number of suffixes to indicate various different flavors of a primitive beyond just different data types. The flavor suffix uses the following abbreviations:</p>
<ul>
<li>"A" if the image is a 4 channel image this indicates the result alpha channel is not affected by the primitive.</li>
<li>"Cn" the image consists of n channel packed pixels, where n can be 1, 2, 3 or 4.</li>
<li>"Pn" the image consists of n separate image planes, where n can be 1, 2, 3 or 4.</li>
<li>"C" (following the channel information) indicates that the primitive only operates on one of the color channels, the "channel-of-interest". All other output channels are not affected by the primitive.</li>
<li>"I" indicates that the primitive works "in-place". In this case the image-data pointer is usually named "pSrcDst" to indicate that the image data serves as source and destination at the same time.</li>
<li>"M" indicates "masked operation". These types of primitives have an additional "mask image" as as input. Each pixel in the destination image corresponds to a pixel in the mask image. Only pixels with a corresponding non-zero mask pixel are being processed.</li>
<li>"R" indicates the primitive operates only on a rectangular "region-of-interest" or "ROI". All ROI primitives take an additional input parameter of type <a class="el" href="struct_nppi_size.html" title="2D Size This struct typically represents the size of a a rectangular region in two space...">NppiSize</a>, which specifies the width and height of the rectangular region that the primitive should process. For details on how primitives operate on ROIs see: <a class="el" href="nppi_conventions_lb.html#roi_specification">Region-of-Interest (ROI)</a>.</li>
<li>"Sfs" indicates the result values are processed by fixed scaling and saturation before they're written out.</li>
</ul>
<p>The suffixes above always appear in alphabetical order. E.g. a 4 channel primitive not affecting the alpha channel with masked operation, in place and with scaling/saturation and ROI would have the postfix: "AC4IMRSfs".</p>
<h1><a class="anchor" id="passing_image_data"></a>
Image Data</h1>
<p>Image data is passed to and from NPPI primitives via a pair of parameters:</p>
<ol type="1">
<li>A pointer to the image's underlying data type.</li>
<li>A line step in bytes (also sometimes called line stride).</li>
</ol>
<p>The general idea behind this fairly low-level way of passing image data is ease-of-adoption into existing software projects:</p>
<ul>
<li>Passing a raw pointer to the underlying pixel data type, rather than structured (by color) channel pixel data allows usage of the function in a wide variety of situations avoiding risky type cast or expensive image data copies.</li>
<li>Passing the data pointer and line step individually rather than a higher- level image struct again allows for easy adoption by not requiring a specific image representation and thus avoiding awkward packing and unpacking of image data from the host application to an NPP specific image representation.</li>
</ul>
<h2><a class="anchor" id="line_step"></a>
Line Step</h2>
<p>The line step (also called "line stride" or "row step") allows lines of oddly sized images to start on well-aligned addresses by adding a number of unused bytes at the ends of the lines. This type of line padding has been common practice in digital image processing for a long time and is not particular to GPU image processing.</p>
<p>The line step is the number of bytes in a line <b>including the padding.</b> An other way to interpret this number is to say that it is the number of bytes between the first pixel of successive rows in the image, or generally the number of bytes between two neighboring pixels in any column of pixels.</p>
<p>The general reason for the existence of the line step it is that uniformly aligned rows of pixel enable optimizations of memory-access patterns.</p>
<p>Even though all functions in NPP will work with arbitrarily aligned images, best performance can only be achieved with well aligned image data. Any image data allocated with the NPP image allocators or the 2D memory allocators in the CUDA runtime, is well aligned.</p>
<p>Particularly on older CUDA capable GPUs it is likely that the performance decrease for misaligned data is substantial (orders of magnitude).</p>
<p>All image data passed to NPPI primitives requires a line step to be provided. It is important to keep in mind that this line step is always specified in terms of bytes, not pixels.</p>
<h2><a class="anchor" id="image_data_parameter_names"></a>
Parameter Names for Image Data</h2>
<p>There are three general cases of image-data passing throughout NPP detailed in the following sections.</p>
<h3><a class="anchor" id="source_image"></a>
Passing Source-Image Data</h3>
<p>Those are images consumed by the algorithm.</p>
<h4><a class="anchor" id="source_image_pointer"></a>
Source-Image Pointer</h4>
<p>The source image data is generally passed via a pointer named </p>
<div class="fragment"><div class="line">pSrc </div>
</div><!-- fragment --><p> The source image pointer is generally defined constant, enforcing that the primitive does not change any image data pointed to by that pointer. E.g. </p>
<div class="fragment"><div class="line">nppiPrimitive_32s_C1R(<span class="keyword">const</span> <a class="code" href="group__npp__basic__types.html#gafa3572058d57d93e2e5ebb9b21fbedb3">Npp32s</a> * pSrc, ...) </div>
</div><!-- fragment --><p> In case the primitive consumes multiple images as inputs the source pointers are numbered like this: </p>
<div class="fragment"><div class="line">pSrc1, pScr2, ... </div>
</div><!-- fragment --><h4><a class="anchor" id="source_planar_image_pointer_array"></a>
Source-Planar-Image Pointer Array</h4>
<p>The planar source image data is generally passed via an array of pointers named </p>
<div class="fragment"><div class="line">pSrc[] </div>
</div><!-- fragment --><p> The planar source image pointer array is generally defined a constant array of constant pointers, enforcing that the primitive does not change any image data pointed to by those pointers. E.g. </p>
<div class="fragment"><div class="line">nppiPrimitive_8u_P3R(<span class="keyword">const</span> <a class="code" href="group__npp__basic__types.html#ga29b502b6816fc0066fd59538483a5b62">Npp8u</a> * <span class="keyword">const</span> pSrc[3], ...) </div>
</div><!-- fragment --><p> Each pointer in the array points to a different image plane.</p>
<h4><a class="anchor" id="source_planar_image_pointer"></a>
Source-Planar-Image Pointer</h4>
<p>The multiple plane source image data is passed via a set of pointers named </p>
<div class="fragment"><div class="line">pSrc1, pSrc2, ... </div>
</div><!-- fragment --><p> The planar source image pointer is generally defined as one of a set of constant pointers with each pointer pointing to a different input image plane.</p>
<h4><a class="anchor" id="source_image_line_step"></a>
Source-Image Line Step</h4>
<p>The source image line step is the number of bytes between successive rows in the image. The source image line step parameter is </p>
<div class="fragment"><div class="line">nSrcStep </div>
</div><!-- fragment --><p> or in the case of multiple source images </p>
<div class="fragment"><div class="line">nSrcStep1, nSrcStep2, ... </div>
</div><!-- fragment --><h4><a class="anchor" id="source_planar_image_line_step_array"></a>
Source-Planar-Image Line Step Array</h4>
<p>The source planar image line step array is an array where each element of the array contains the number of bytes between successive rows for a particular plane in the input image. The source planar image line step array parameter is </p>
<div class="fragment"><div class="line">rSrcStep[] </div>
</div><!-- fragment --><h4><a class="anchor" id="source_planar_image_line_step"></a>
Source-Planar-Image Line Step</h4>
<p>The source planar image line step is the number of bytes between successive rows in a particular plane of the multiplane input image. The source planar image line step parameter is </p>
<div class="fragment"><div class="line">nSrcStep1, nSrcStep2, ... </div>
</div><!-- fragment --><h3><a class="anchor" id="destination_image"></a>
Passing Destination-Image Data</h3>
<p>Those are images produced by the algorithm.</p>
<h4><a class="anchor" id="destination_image_pointer"></a>
Destination-Image Pointer</h4>
<p>The destination image data is generally passed via a pointer named </p>
<div class="fragment"><div class="line">pDst </div>
</div><!-- fragment --><p> In case the primitive generates multiple images as outputs the destination pointers are numbered like this: </p>
<div class="fragment"><div class="line">pDst1, pDst2, ... </div>
</div><!-- fragment --><h4><a class="anchor" id="destination_planar_image_pointer_array"></a>
Destination-Planar-Image Pointer Array</h4>
<p>The planar destination image data pointers are generally passed via an array of pointers named </p>
<div class="fragment"><div class="line">pDst[] </div>
</div><!-- fragment --><p> Each pointer in the array points to a different image plane.</p>
<h4><a class="anchor" id="destination_planar_image_pointer"></a>
Destination-Planar-Image Pointer</h4>
<p>The destination planar image data is generally passed via a pointer to each plane of a multiplane output image named </p>
<div class="fragment"><div class="line">pDst1, pDst2, ... </div>
</div><!-- fragment --><h4><a class="anchor" id="destination_image_line_step"></a>
Destination-Image Line Step</h4>
<p>The destination image line step parameter is </p>
<div class="fragment"><div class="line">nDstStep </div>
</div><!-- fragment --><p> or in the case of multiple destination images </p>
<div class="fragment"><div class="line">nDstStep1, nDstStep2, ... </div>
</div><!-- fragment --><h4><a class="anchor" id="destination_planar_image_line_step_array"></a>
Destination-Planar-Image Line Step Array</h4>
<p>The destination planar image line step array is an array where each element of the array contains the number of bytes between successive rows for a particular plane in the output image. The destination planar image line step array parameter is </p>
<div class="fragment"><div class="line">rDstStep[] </div>
</div><!-- fragment --><h4><a class="anchor" id="destination_planar_image_line_step"></a>
Destination-Planar-Image Line Step</h4>
<p>The destination planar image line step is the number of bytes between successive rows for a particular plane in a multiplane output image. The destination planar image line step parameter is </p>
<div class="fragment"><div class="line">nDstStep1, nDstStep2, ... </div>
</div><!-- fragment --><h3><a class="anchor" id="in_place_image"></a>
Passing In-Place Image Data</h3>
<h4><a class="anchor" id="in_place_image_pointer"></a>
In-Place Image Pointer</h4>
<p>In the case of in-place processing, source and destination are served by the same pointer and thus pointers to in-place image data are called: </p>
<div class="fragment"><div class="line">pSrcDst </div>
</div><!-- fragment --><h4><a class="anchor" id="in_place_image_line_step"></a>
In-Place-Image Line Step</h4>
<p>The in-place line step parameter is </p>
<div class="fragment"><div class="line">nSrcDstStep </div>
</div><!-- fragment --><h3><a class="anchor" id="mask_image"></a>
Passing Mask-Image Data</h3>
<p>Some image processing primitives have variants supporting <a class="el" href="nppi_conventions_lb.html#masked_operation">Masked Operation</a>.</p>
<h4><a class="anchor" id="mask_image_pointer"></a>
Mask-Image Pointer</h4>
<p>The mask-image data is generally passed via a pointer named </p>
<div class="fragment"><div class="line">pMask </div>
</div><!-- fragment --><h4><a class="anchor" id="mask_image_line_step"></a>
Mask-Image Line Step</h4>
<p>The mask-image line step parameter is </p>
<div class="fragment"><div class="line">nMaskStep </div>
</div><!-- fragment --><h3><a class="anchor" id="channel_of_interest_section"></a>
Passing Channel-of-Interest Data</h3>
<p>Some image processing primitives support <a class="el" href="nppi_conventions_lb.html#channel_of_interest">Channel-of-Interest API</a>.</p>
<h4><a class="anchor" id="channel_of_interest_number"></a>
Channel_of_Interest Number</h4>
<p>The channel-of-interest data is generally an integer (either 1, 2, or 3): </p>
<div class="fragment"><div class="line">nCOI </div>
</div><!-- fragment --><h2><a class="anchor" id="image_data_alignment"></a>
Image Data Alignment Requirements</h2>
<p>NPP requires pixel data to adhere to certain alignment constraints: For 2 and 4 channel images the following alignment requirement holds: data_pointer % (#channels * sizeof(channel type)) == 0. E.g. a 4 channel image with underlying type <a class="el" href="group__npp__basic__types.html#ga29b502b6816fc0066fd59538483a5b62" title="8-bit unsigned chars ">Npp8u</a> (8-bit unsigned) would require all pixels to fall on addresses that are multiples of 4 (4 channels * 1 byte size).</p>
<p>As a logical consequence of all pixels being aligned to their natural size the image line steps of 2 and 4 channel images also need to be multiples of the pixel size.</p>
<p>1 and 3 channel images only require that pixel pointers are aligned to the underlying data type, i.e. pData % sizof(data type) == 0. And consequentially line steps are also held to this requirement.</p>
<h2><a class="anchor" id="image_data_error_codes"></a>
Image Data Related Error Codes</h2>
<p>All NPPI primitives operating on image data validate the image-data pointer for proper alignment and test that the point is not null. They also validate the line stride for proper alignment and guard against the step being less or equal to 0. Failed validation results in one of the following error codes being returnd and the primitive not being executed:</p>
<ul>
<li><a class="el" href="group__typedefs__npp.html#gga1105a17b5e76381583c46ecd6a60fe21a582d1a09141f3b175a2e751cfc2e22cd" title="Step is less or equal zero. ">NPP_STEP_ERROR</a> is returned if the data step is 0 or negative.</li>
<li><a class="el" href="group__typedefs__npp.html#gga1105a17b5e76381583c46ecd6a60fe21a8c513cfa03ef5d03cc8dd35421738b60" title="Step value is not pixel multiple. ">NPP_NOT_EVEN_STEP_ERROR</a> is returned if the line step is not a multiple of the pixel size for 2 and 4 channel images.</li>
<li><a class="el" href="group__typedefs__npp.html#gga1105a17b5e76381583c46ecd6a60fe21a524a376b3d44c458b474613fb0dc8e1a">NPP_NULL_POINTER_ERROR</a> is returned if the image-data pointer is 0 (NULL).</li>
<li><a class="el" href="group__typedefs__npp.html#gga1105a17b5e76381583c46ecd6a60fe21ab1b34e6935a87a4f0018e783ad86cf1b">NPP_ALIGNMENT_ERROR</a> if the image-data pointer address is not a multiple of the pixel size for 2 and 4 channel images.</li>
</ul>
<h1><a class="anchor" id="roi_specification"></a>
Region-of-Interest (ROI)</h1>
<p>In practice processing a rectangular sub-region of an image is often more common than processing complete images. The vast majority of NPP's image-processing primitives allow for processing of such sub regions also referred to as regions-of-interest or ROIs.</p>
<p>All primitives supporting ROI processing are marked by a "R" in their name suffix. In most cases the ROI is passed as a single <a class="el" href="struct_nppi_size.html" title="2D Size This struct typically represents the size of a a rectangular region in two space...">NppiSize</a> struct, which provides the with and height of the ROI. This raises the question how the primitive knows where in the image this rectangle of (width, height) is located. The "start pixel" of the ROI is implicitly given by the image-data pointer. I.e. instead of explicitly passing a pixel coordinate for the upper-left corner (lowest memory address), the user simply offsets the image-data pointers to point to the first pixel of the ROI.</p>
<p>In practice this means that for an image (pSrc, nSrcStep) and the start-pixel of the ROI being at location (x, y), one would pass</p>
<p>pSrcOffset = pSrc + y * nSrcStep + x * PixelSize;</p>
<p>as the image-data source to the primitive. PixelSize is typically computed as</p>
<p>PixelSize = NumberOfColorChannels * sizeof(PixelDataType).</p>
<p>E.g. for a pimitive like <a class="el" href="group__image__set.html#ga217e8dacb892f5f24ab1789a0fdae0b2">nppiSet_16s_C4R()</a> we would have</p>
<ul>
<li>NumberOfColorChannels == 4;</li>
<li>sizeof(Npp16s) == 2;</li>
<li>and thus PixelSize = 4 * 2 = 8;</li>
</ul>
<h2><a class="anchor" id="roi_error_codes"></a>
ROI Related Error Codes</h2>
<p>All NPPI primitives operating on ROIs of image data validate the ROI size and image's step size. Failed validation results in one of the following error codes being returned and the primitive not being executed:</p>
<ul>
<li><a class="el" href="group__typedefs__npp.html#gga1105a17b5e76381583c46ecd6a60fe21a63297527390b522fa2b47a4d82f71b4b">NPP_SIZE_ERROR</a> is returned if either the ROI width or ROI height are negative.</li>
<li><a class="el" href="group__typedefs__npp.html#gga1105a17b5e76381583c46ecd6a60fe21a582d1a09141f3b175a2e751cfc2e22cd" title="Step is less or equal zero. ">NPP_STEP_ERROR</a> is returned if the ROI width exceeds the image's line step. In mathematical terms (widthROI * PixelSize) > nLinStep indicates an error.</li>
</ul>
<h1><a class="anchor" id="masked_operation"></a>
Masked Operation</h1>
<p>Some primitive support masked operation. An "M" in the suffix of those variants indicates masked operation. Primitives supporting masked operation consume an additional input image provided via a <a class="el" href="nppi_conventions_lb.html#mask_image_pointer">Mask-Image Pointer</a> and <a class="el" href="nppi_conventions_lb.html#mask_image_line_step">Mask-Image Line Step</a>. The mask image is interpreted by these primitives as a boolean image. The values of type Npp8u are interpreted as boolean values where a values of 0 indicates false, any non-zero values true.</p>
<p>Unless otherwise indicated the operation is only performed on pixels where its spatially corresponding mask pixel is true (non-zero). E.g. a masked copy operation would only copy those pixels in the ROI that have corresponding non-zero mask pixels.</p>
<h1><a class="anchor" id="channel_of_interest"></a>
Channel-of-Interest API</h1>
<p>Some primitives allow restricting operations to a single channel of interest within a multi-channel image. These primitives are suffixed with the letter "C" (after the channel information, e.g. nppiCopy_8u_C3CR(...). The channel-of-interest is generally selected by offsetting the image-data pointer to point directly to the channel- of-interest rather than the base of the first pixel in the ROI. Some primitives also explicitly specify the selected channel number and pass it via an integer, e.g. nppiMean_StdDev_8u_C3CR(...).</p>
<h2><a class="anchor" id="select_source_pointer"></a>
Select-Channel Source-Image Pointer</h2>
<p>This is a pointer to the channel-of-interest within the first pixel of the source image. E.g. if pSrc is the pointer to the first pixel inside the ROI of a three channel image. Using the appropriate select-channel copy primitive one could copy the second channel of this source image into the first channel of a destination image given by pDst by offsetting the pointer by one: </p>
<div class="fragment"><div class="line">* <a class="code" href="group__image__channel__copy.html#ga01990d24931f7822929a3f582cf08fcf">nppiCopy_8u_C3CR</a>(pSrc + 1, nSrcStep, pDst, nDstStep, oSizeROI);</div>
<div class="line">* </div>
</div><!-- fragment --><h2><a class="anchor" id="select_source_channel"></a>
Select-Channel Source-Image</h2>
<p>Some primitives allow the user to select the channel-of-interest by specifying the channle number (nCOI). This approach is typically used in the image statistical functions. For example, </p>
<div class="fragment"><div class="line">* <a class="code" href="group__image__mean__stddev.html#ga00d110048082bd3315093a20ea04fd0d">nppiMean_StdDev_8u_C3CR</a>(pSrc, nSrcStep, oSizeROI, nCOI, pDeviceBuffer, pMean, pStdDev );</div>
<div class="line">* </div>
</div><!-- fragment --><p> The channel-of-interest number can be either 1, 2, or 3.</p>
<h2><a class="anchor" id="select_destination_pointer"></a>
Select-Channel Destination-Image Pointer</h2>
<p>This is a pointer to the channel-of-interest within the first pixel of the destination image. E.g. if pDst is the pointer to the first pixel inside the ROI of a three channel image. Using the appropriate select-channel copy primitive one could copy data into the second channel of this destination image from the first channel of a source image given by pSrc by offseting the destination pointer by one: </p>
<div class="fragment"><div class="line">* <a class="code" href="group__image__channel__copy.html#ga01990d24931f7822929a3f582cf08fcf">nppiCopy_8u_C3CR</a>(pSrc, nSrcStep, pDst + 1, nDstStep, oSizeROI);</div>
<div class="line">* </div>
</div><!-- fragment --><h1><a class="anchor" id="source_image_sampling"></a>
Source-Image Sampling</h1>
<p>A large number of NPP image-processing functions consume at least one source image and produce an output image (e.g. <a class="el" href="group__image__addc.html#gaa9d2480694acd95de34b77153014a9b5">nppiAddC_8u_C1RSfs()</a> or <a class="el" href="group__image__filter__box.html#ga862d35eb4a41a230cae4f4c58564f160">nppiFilterBox_8u_C1R()</a>). All NPP functions falling into this category also operate on ROIs (see <a class="el" href="nppi_conventions_lb.html#roi_specification">Region-of-Interest (ROI)</a>) which for these functions should be considered to describe the destination ROI. In other words the ROI describes a rectangular region in the destination image and all pixels inside of this region are being written by the function in question.</p>
<p>In order to use such functions successfully it is important to understand how the user defined destination ROI affects which pixels in the input image(s) are being read by the algorithms. To simplify the discussion of ROI propagation (i.e. given a destination ROI, what are the ROIs in in the source(s)), it makes sense to distinguish two major cases:</p>
<ol type="1">
<li>Point-Wise Operations: These are primitives like <a class="el" href="group__image__addc.html#gaa9d2480694acd95de34b77153014a9b5">nppiAddC_8u_C1RSfs()</a>. Each output pixel requires exaclty one input pixel to be read.</li>
<li>Neighborhood Operations: These are primitives like <a class="el" href="group__image__filter__box.html#ga862d35eb4a41a230cae4f4c58564f160">nppiFilterBox_8u_C1R()</a>, which require a group of pixels from the source image(s) to be read in order to produce a single output.</li>
</ol>
<h2><a class="anchor" id="point_wise_operations"></a>
Point-Wise Operations</h2>
<p>As mentioned above, point-wise operations consume a single pixel from the input image (or a single pixel from each input image, if the operation in question has more than one input image) in order to produce a single output pixel.</p>
<h2><a class="anchor" id="neighborhood_operations"></a>
Neighborhood Operations</h2>
<p>In the case of neightborhood operations a number of input pixels (a "neighborhood" of pixels) is read in the input image (or images) in order to compute a single output pixel. All of the functions for <a class="el" href="group__image__filtering__functions.html">Filtering Functions</a> and <a class="el" href="group__image__morphological__operations.html">Morphological Operations</a> are neigborhood operations.</p>
<p>Most of these functions have parameters that affect the size and relative location of the neighborhood: a mask-size structure and an achor-point structure. Both parameters are described in more detail in the next subsections.</p>
<h3><a class="anchor" id="mask_size_parameter"></a>
Mask-Size Parameter</h3>
<p>Many NPP neighborhood operations allow the user to specify the size of the neightborhood via a parameter usually named oMaskSize of type <a class="el" href="struct_nppi_size.html" title="2D Size This struct typically represents the size of a a rectangular region in two space...">NppiSize</a>. In those cases the neighborhood of pixels read from the source(s) is exactly the size of the mask. Assuming the mask is anchored at location (0, 0) (see <a class="el" href="nppi_conventions_lb.html#anchor_point_parameter">Anchor-Point Parameter</a> below) and has a size of (w, h), i.e. </p>
<div class="fragment"><div class="line">* assert(oMaskSize.w == w);</div>
<div class="line">* assert(oMaskSize.h == h);</div>
<div class="line">* assert(oAnchor.x == 0);</div>
<div class="line">* assert(oAnchor.y == 0);</div>
<div class="line">* </div>
</div><!-- fragment --><p> a neighborhood operation would read the following source pixels in order to compute destiation pixel <img class="formulaInl" alt="$ D_{i,j} $" src="form_132.png"/>: </p>
<p class="formulaDsp">
<img class="formulaDsp" alt="\[ \begin{array}{lllll} S_{i,j} & S_{i,j+1} & \ldots & S_{i,j+w-1} \\ S_{i+1,j} & S_{i+1,j+1} & \ldots & S_{i+1, j+w-1} \\ \vdots & \vdots & \ddots & \vdots \\ S_{i+h-1, j} & S_{i+h-1, j+1} & \ldots & S_{i+h-1, j+w-1} \end{array} \]" src="form_133.png"/>
</p>
<h3><a class="anchor" id="anchor_point_parameter"></a>
Anchor-Point Parameter</h3>
<p>Many NPP primitives perforing neighborhood operations allow the user to specify the relative location of the neighborhood via a parameter usually named oAnchor of type <a class="el" href="struct_nppi_point.html" title="2D Point ">NppiPoint</a>. Using the anchor a developer can chose the position of the mask (see <a class="el" href="nppi_conventions_lb.html#mask_size_parameter">Mask-Size Parameter</a>) relative to current pixel index.</p>
<p>Using the same example as in <a class="el" href="nppi_conventions_lb.html#mask_size_parameter">Mask-Size Parameter</a>, but this time with an anchor position of (a, b): </p>
<div class="fragment"><div class="line">* assert(oMaskSize.w == w);</div>
<div class="line">* assert(oMaskSize.h == h);</div>
<div class="line">* assert(oAnchor.x == a);</div>
<div class="line">* assert(oAnchor.y == b);</div>
<div class="line">* </div>
</div><!-- fragment --><p> the following pixels from the source image would be read: </p>
<p class="formulaDsp">
<img class="formulaDsp" alt="\[ \begin{array}{lllll} S_{i-a,j-b} & S_{i-a,j-b+1} & \ldots & S_{i-a,j-b+w-1} \\ S_{i-a+1,j-b} & S_{i-a+1,j-b+1} & \ldots & S_{i-a+1, j-b+w-1} \\ \vdots & \vdots & \ddots & \vdots \\ S_{i-a+h-1, j-b} & S_{i-a+h-1, j-b+1} & \ldots & S_{i-a+h-1, j-b+w-1} \end{array} \]" src="form_134.png"/>
</p>
<h3><a class="anchor" id="sampling_beyond_image_boundaries"></a>
Sampling Beyond Image Boundaries</h3>
<p>NPP primitives in general and NPP neighborhood operations in particular require that all pixel locations read and written are valid and within the boundaries of the respective images. Sampling outside of the defined image data regions results in undefined behavior and may lead to system instabilty.</p>
<p>This poses a problem in practice: when processing full-size images one cannot choose the destination ROI to be the same size as the source image. Because neigborhood operations read pixels from an enlarged source ROI, the destination ROI must be shrunk so that the expanded source ROI does not exceed the source image's size.</p>
<p>For cases where this "shrinking" of the destination image size is unacceptable, NPP provides a set of border-expanding Copy primitives. E.g. <a class="el" href="group__image__copy__constant__border.html#ga8e040e14af9edf095b4c12b97453920e">nppiCopyConstBorder_8u_C1R()</a>, <a class="el" href="group__image__copy__replicate__border.html#ga10c5d07faf1ff74af682019d8cb94e04">nppiCopyReplicateBorder_8u_C1R()</a> and <a class="el" href="group__image__copy__wrap__border.html#ga235129584353176f8f60593f3fb1af0f">nppiCopyWrapBorder_8u_C1R()</a>. The user can use these primitives to "expand" the source image's size using one of the three expansion modes. The expanded image can then be safely passed to a neighborhood operation producing a full-size result. </p>
</div></div><!-- contents -->
<HR>
<center>Copyright © 2009-2019 NVIDIA Corporation</center>
<HR>
distrib
>
Mageia
>
7
>
x86_64
>
media
>
nonfree-updates
>
by-pkgid
>
b86a85131cc739c1c53d0b55840a4328
>
files
>
2203
