PCL
pcl::AbstractImage Class Reference

Base class of all two-dimensional images in PCL. More...

#include <AbstractImage.h>

+ Inheritance diagram for pcl::AbstractImage:

Classes

struct  ThreadData
 Thread synchronization data for status monitoring of parallel image processing tasks. More...
 

Public Types

using color_space = ImageColor::color_space
 
using selection_stack = Array< ImageSelections >
 
- Public Types inherited from pcl::ImageColor
using color_space = ColorSpace::value_type
 

Public Member Functions

 ~AbstractImage () override
 
bool CanPopSelections () const noexcept
 
void DisableRangeClipping (bool disableLow=true, bool disableHigh=true) const noexcept
 
void EnableRangeClipping (bool enableLow=true, bool enableHigh=true) const noexcept
 
int FirstSelectedChannel () const noexcept
 
void GetSelectedChannelRange (int &c0, int &c1) const noexcept
 
pcl::StatusCallbackGetStatusCallback () const noexcept
 
bool HasAlphaChannels () const noexcept
 
bool IsCompletelySelected () const noexcept
 
bool IsEmptySelection () const noexcept
 
bool IsFullSelection () const noexcept
 
bool IsHighRangeClippingEnabled () const noexcept
 
bool IsLowRangeClippingEnabled () const noexcept
 
bool IsRangeClippingEnabled () const noexcept
 
int LastSelectedChannel () const noexcept
 
int NumberOfAlphaChannels () const noexcept
 
size_type NumberOfAlphaSamples () const noexcept
 
int NumberOfNominalChannels () const noexcept
 
size_type NumberOfNominalSamples () const noexcept
 
int NumberOfSelectedChannels () const noexcept
 
size_type NumberOfSelectedPixels () const noexcept
 
size_type NumberOfSelectedSamples () const noexcept
 
int NumberOfThreads (size_type count, int maxProcessors=0, size_type overheadLimit=16u) const noexcept
 
int NumberOfThreadsForRows (int rowCount=0, int rowWidth=0, int maxProcessors=0, size_type overheadLimitPx=1024u) const noexcept
 
Array< size_typeOptimalThreadRows (int rowCount=0, int rowWidth=0, int maxProcessors=0, size_type overheadLimitPx=1024u) const noexcept
 
bool ParseChannel (int &channel) const noexcept
 
bool ParseRect (Rect &rect) const noexcept
 
bool ParseSelection (Rect &rect, int &channel) const noexcept
 
bool ParseSelection (Rect &rect, int &firstChannel, int &lastChannel) const noexcept
 
void PopSelections () const
 
void PushSelections () const
 
double RangeClipHigh () const noexcept
 
double RangeClipLow () const noexcept
 
void ResetChannelRange () const noexcept
 
void ResetPoint () const noexcept
 
void ResetRangeClipping () const noexcept
 
void ResetSelection () const noexcept
 
void ResetSelections () const noexcept
 
void SelectAlphaChannels () const noexcept
 
void SelectChannel (int c) const noexcept
 
void SelectChannelRange (int c0, int c1) const noexcept
 
int SelectedChannel () const noexcept
 
const PointSelectedPoint () const noexcept
 
const RectSelectedRectangle () const noexcept
 
ImageSelectionsSelections () const noexcept
 
void SelectNominalChannels () const noexcept
 
void SelectPoint (const Point &p) const noexcept
 
void SelectPoint (int x, int y) const noexcept
 
void SelectRectangle (const Point &p0, const Point &p1) const noexcept
 
void SelectRectangle (const Rect &r) const noexcept
 
void SelectRectangle (int x0, int y0, int x1, int y1) const noexcept
 
void SetRangeClipHigh (double clipHigh) const noexcept
 
void SetRangeClipLow (double clipLow) const noexcept
 
void SetRangeClipping (double clipLow, double clipHigh) const noexcept
 
void SetStatusCallback (pcl::StatusCallback *callback) const noexcept
 
StatusMonitorStatus () const noexcept
 
pcl::StatusCallbackStatusCallback () const noexcept
 
- Public Member Functions inherited from pcl::ImageGeometry
Rect Bounds () const noexcept
 
template<typename T >
bool Clip (pcl::GenericPoint< T > &p) const noexcept
 
template<typename T >
bool Clip (pcl::GenericRectangle< T > &r) const noexcept
 
template<typename T >
bool Clip (T &x, T &y) const noexcept
 
template<typename T >
bool Clip (T &x0, T &y0, T &x1, T &y1) const noexcept
 
int Height () const noexcept
 
template<typename T >
bool Includes (const GenericPoint< T > &p) const noexcept
 
template<typename T >
bool Includes (const GenericRectangle< T > &r) const noexcept
 
template<typename T >
bool Includes (T x, T y) const noexcept
 
template<typename T >
bool Includes (T x0, T y0, T x1, T y1) const noexcept
 
template<typename T >
bool Intersects (const pcl::GenericRectangle< T > &r) const noexcept
 
template<typename T >
bool Intersects (T x0, T y0, T x1, T y1) const noexcept
 
bool IsEmpty () const noexcept
 
bool IsValidChannelIndex (int c) const noexcept
 
int LastChannel () const noexcept
 
int NumberOfChannels () const noexcept
 
size_type NumberOfPixels () const noexcept
 
size_type NumberOfSamples () const noexcept
 
distance_type PixelOffset (int x, int y) const noexcept
 
distance_type RowOffset (int y) const noexcept
 
int Width () const noexcept
 
- Public Member Functions inherited from pcl::ImageColor
String ChannelId (int c) const noexcept
 
color_space ColorSpace () const noexcept
 
bool IsColor () const noexcept
 
const RGBColorSystemRGBWorkingSpace () const noexcept
 
virtual void SetRGBWorkingSpace (const RGBColorSystem &RGBWS)
 
- Public Member Functions inherited from pcl::ParallelProcess
 ParallelProcess ()=default
 
 ParallelProcess (const ParallelProcess &)=default
 
virtual ~ParallelProcess ()
 
void DisableParallelProcessing (bool disable=true) noexcept
 
void EnableParallelProcessing (bool enable=true, int maxProcessors=0) noexcept
 
bool IsParallelProcessingEnabled () const noexcept
 
int MaxProcessors () const noexcept
 
ParallelProcessoperator= (const ParallelProcess &)=default
 
void SetMaxProcessors (int maxProcessors) noexcept
 
void Swap (ParallelProcess &process) noexcept
 

Static Public Member Functions

template<class thread >
static void RunThreads (ReferenceArray< thread > &threads, ThreadData &data, bool useAffinity=true)
 
- Static Public Member Functions inherited from pcl::ImageColor
static const RGBColorSystemDefaultRGBWorkingSpace () noexcept
 
static void ResetDefaultRGBWorkingSpace ()
 
static void SetDefaultRGBWorkingSpace (const RGBColorSystem &RGBWS)
 

Detailed Description

AbstractImage encapsulates ImageGeometry and ImageColor into a single class employed as the root base class for all two-dimensional images in PCL.

This class provides fundamental properties and functionality that are independent on the particular data types used to store and manage pixel samples.

AbstractImage also provides a simple selection mechanism consisting of a rectangular selection (also known as region of interest, or ROI), a channel range, and an anchor point. Image selections can be stored in a local stack for quick retrieval (see PushSelections() and PopSelections()). Note that for practical reasons, image selections have been implemented as mutable data members internally, so modifying selections is possible for immutable AbstractImage instances.

Finally, AbstractImage provides function and data members to manage status monitoring of images. The status monitoring mechanism can be used to provide feedback to the user about the progress of a running process. Status monitoring is implemented through the StatusMonitor and StatusCallback classes. See the Status(), StatusCallback() and SetStatusCallback() member functions for more information.

See also
ImageGeometry, ImageColor, GenericImage, ImageVariant

Definition at line 118 of file AbstractImage.h.

Member Typedef Documentation

◆ color_space

using pcl::AbstractImage::color_space = ImageColor::color_space

An enumerated type that represents the set of supported color spaces. Valid constants for this enumeration are defined in the ColorSpace namespace.

Definition at line 134 of file AbstractImage.h.

◆ selection_stack

A type used to implement a stack of stored image selections.

Definition at line 127 of file AbstractImage.h.

Constructor & Destructor Documentation

◆ ~AbstractImage()

pcl::AbstractImage::~AbstractImage ( )
inlineoverride

Virtual destructor.

Definition at line 139 of file AbstractImage.h.

Member Function Documentation

◆ CanPopSelections()

bool pcl::AbstractImage::CanPopSelections ( ) const
inlinenoexcept

Returns true iff one or more selections have been pushed to the internal selection stack, that is, if the PopSelections() function can be called to restore them.

Definition at line 674 of file AbstractImage.h.

◆ DisableRangeClipping()

void pcl::AbstractImage::DisableRangeClipping ( bool  disableLow = true,
bool  disableHigh = true 
) const
inlinenoexcept

Disables range clippings for statistical calculations.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 529 of file AbstractImage.h.

◆ EnableRangeClipping()

void pcl::AbstractImage::EnableRangeClipping ( bool  enableLow = true,
bool  enableHigh = true 
) const
inlinenoexcept

Enables range clippings for statistical calculations.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 518 of file AbstractImage.h.

◆ FirstSelectedChannel()

int pcl::AbstractImage::FirstSelectedChannel ( ) const
inlinenoexcept

Returns the channel index of the first selected channel.

Definition at line 282 of file AbstractImage.h.

◆ GetSelectedChannelRange()

void pcl::AbstractImage::GetSelectedChannelRange ( int &  c0,
int &  c1 
) const
inlinenoexcept

Copies the first and last channel indices of the current channel selection to the specified variables.

Parameters
[out]c0Index of the first selected channel.
[out]c1Index of the last selected channel.

Definition at line 302 of file AbstractImage.h.

◆ GetStatusCallback()

pcl::StatusCallback* pcl::AbstractImage::GetStatusCallback ( ) const
inlinenoexcept
Deprecated:
This function has been deprecated. It is included in this version of PCL to keep existing code functional. Use StatusCallback() in newly produced code.

Definition at line 819 of file AbstractImage.h.

◆ HasAlphaChannels()

bool pcl::AbstractImage::HasAlphaChannels ( ) const
inlinenoexcept

Returns true iff this image has one or more alpha channels.

Alpha channels are those in excess of nominal channels, e.g. a fourth channel in a RGB image, or a second channel in a grayscale image.

Definition at line 167 of file AbstractImage.h.

References pcl::ColorSpace::NumberOfNominalChannels().

◆ IsCompletelySelected()

bool pcl::AbstractImage::IsCompletelySelected ( ) const
inlinenoexcept

Returns true if this image is completely selected; false if it is only partially selected.

In a completely selected image, the current rectangular selection includes the whole image, and the current channel range selection comprises all existing channels, including nominal and alpha channels.

Definition at line 428 of file AbstractImage.h.

Referenced by pcl::GenericImage< P >::GenericImage().

◆ IsEmptySelection()

bool pcl::AbstractImage::IsEmptySelection ( ) const
inlinenoexcept

Returns true iff the current selection is empty, i.e. if its area is zero.

Definition at line 395 of file AbstractImage.h.

◆ IsFullSelection()

bool pcl::AbstractImage::IsFullSelection ( ) const
inlinenoexcept

Returns true iff the current rectangular selection comprises the entire image.

Definition at line 404 of file AbstractImage.h.

◆ IsHighRangeClippingEnabled()

bool pcl::AbstractImage::IsHighRangeClippingEnabled ( ) const
inlinenoexcept

Returns true iff range clipping is currently enabled for the high clipping bound. When this is true, pixel samples with values greater than or equal to the high clipping bound (as reported by RangeClipHigh() ) will be rejected for statistical calculations.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 508 of file AbstractImage.h.

◆ IsLowRangeClippingEnabled()

bool pcl::AbstractImage::IsLowRangeClippingEnabled ( ) const
inlinenoexcept

Returns true iff range clipping is currently enabled for the low clipping bound. When this is true, pixel samples with values less than or equal to the low clipping bound (as reported by RangeClipLow() ) will be rejected for statistical calculations.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 495 of file AbstractImage.h.

◆ IsRangeClippingEnabled()

bool pcl::AbstractImage::IsRangeClippingEnabled ( ) const
inlinenoexcept

Returns true iff range clipping is currently enabled for this image.

When range clipping is enabled, pixel samples outside the current clipping range:

( RangeClipLow(), RangeClipHigh() )

are ignored by statistics calculation routines. Note that range bounds are always excluded, since the range is open on both sides. The clipping range is always defined in the normalized [0,1] range for all pixel sample data types; the necessary conversions are performed transparently.

When range clipping is disabled, the clipping range is ignored and all pixel samples are considered for statistical calculations.

To make it more flexible, range clipping can be enabled/disabled separately for the low and high bounds.

The default clipping range is the normalized (0,1) range. Range clipping is disabled by default.

Definition at line 482 of file AbstractImage.h.

◆ LastSelectedChannel()

int pcl::AbstractImage::LastSelectedChannel ( ) const
inlinenoexcept

Returns the channel index of the last selected channel.

Definition at line 290 of file AbstractImage.h.

◆ NumberOfAlphaChannels()

int pcl::AbstractImage::NumberOfAlphaChannels ( ) const
inlinenoexcept

Returns the number of existing alpha channels in this image.

Definition at line 176 of file AbstractImage.h.

References pcl::ColorSpace::NumberOfNominalChannels().

◆ NumberOfAlphaSamples()

size_type pcl::AbstractImage::NumberOfAlphaSamples ( ) const
inlinenoexcept

Returns the number of existing alpha samples in this image. The returned value is equal to the number of alpha channels multiplied by the area of the image in square pixels.

Definition at line 187 of file AbstractImage.h.

◆ NumberOfNominalChannels()

int pcl::AbstractImage::NumberOfNominalChannels ( ) const
inlinenoexcept

Returns the number of nominal channels corresponding to the current color space of this image.

Definition at line 147 of file AbstractImage.h.

References pcl::ColorSpace::NumberOfNominalChannels().

◆ NumberOfNominalSamples()

size_type pcl::AbstractImage::NumberOfNominalSamples ( ) const
inlinenoexcept

Returns the number of nominal samples in this image. This is equal to the area in square pixels multiplied by the number of nominal channels.

Definition at line 156 of file AbstractImage.h.

References pcl::ColorSpace::NumberOfNominalChannels().

◆ NumberOfSelectedChannels()

int pcl::AbstractImage::NumberOfSelectedChannels ( ) const
inlinenoexcept

Returns the number of selected channels.

Definition at line 274 of file AbstractImage.h.

Referenced by pcl::ImageInfo::ImageInfo().

◆ NumberOfSelectedPixels()

size_type pcl::AbstractImage::NumberOfSelectedPixels ( ) const
inlinenoexcept

Returns the number of selected pixels. This is the area in square pixels of the current selection rectangle.

Definition at line 442 of file AbstractImage.h.

◆ NumberOfSelectedSamples()

size_type pcl::AbstractImage::NumberOfSelectedSamples ( ) const
inlinenoexcept

Returns the number of selected samples. This is the area in square pixels of the current selection rectangle multiplied by the number of selected channels.

Definition at line 455 of file AbstractImage.h.

◆ NumberOfThreads()

int pcl::AbstractImage::NumberOfThreads ( size_type  count,
int  maxProcessors = 0,
size_type  overheadLimit = 16u 
) const
inlinenoexcept

Returns the maximum number of threads that this image can use concurrently to process a set of items.

Parameters
countNumber of processing units. A processing unit can be a single pixel, a row of pixels, or any suitable item, according to the task being performed by the caller.
maxProcessorsIf a value greater than zero is specified, it is the maximum number of processors allowed, which takes precedence over the current limit set for this image (see the MaxProcessors() and SetMaxProcessors() member functions). If zero or a negative value is specified, it is ignored and the current MaxProcessors() limit is applied.
overheadLimitThread overhead limit in processing units. The function returns a maximum number of threads such that no thread would have to process less processing units than this value. The default overhead limit is 16 processing units.

This function takes into account if parallel processing is currently enabled for this image, as well as the maximum number of processors allowed for the calling process.

See also
Thread::NumberOfThreads()

Definition at line 859 of file AbstractImage.h.

◆ NumberOfThreadsForRows()

int pcl::AbstractImage::NumberOfThreadsForRows ( int  rowCount = 0,
int  rowWidth = 0,
int  maxProcessors = 0,
size_type  overheadLimitPx = 1024u 
) const
inlinenoexcept

Returns the maximum number of threads that this image can use concurrently to process a set of pixel rows.

Parameters
rowCountNumber of pixel rows to be processed. If zero or a negative value is specified, the height of the image in pixels will be used. The default value is zero.
rowWidthWidth in pixels of the ROI being processed. If zero or a negative value is specified, the width of the image in pixels is used. The default value is zero.
maxProcessorsIf a value greater than zero is specified, it is the maximum number of processors allowed, which takes precedence over the current limit set for this image (see the MaxProcessors() and SetMaxProcessors() member functions). If zero or a negative value is specified, it is ignored and the current MaxProcessors() limit is applied. The default value is zero.
overheadLimitPxThread overhead limit in pixels. The function will calculate the minimum number of pixel rows that a single thread can process, based on this value and on the specified rowWidth (or the image's width if zero is passed for that parameter). The default overhead limit is 1024 pixels.

This function takes into account if parallel processing is currently enabled for this image, as well as the maximum number of processors allowed for the calling process.

See also
NumberOfThreads(), Thread::NumberOfThreads()

Definition at line 897 of file AbstractImage.h.

References pcl::Max().

◆ OptimalThreadRows()

Array<size_type> pcl::AbstractImage::OptimalThreadRows ( int  rowCount = 0,
int  rowWidth = 0,
int  maxProcessors = 0,
size_type  overheadLimitPx = 1024u 
) const
inlinenoexcept

Returns a list of per-thread counts optimized for parallel processing of a set of pixel rows.

Parameters
rowCountNumber of pixel rows to be processed. If zero or a negative value is specified, the height of the image in pixels will be used. The default value is zero.
rowWidthWidth in pixels of the ROI being processed. If zero or a negative value is specified, the width of the image in pixels is used. The default value is zero.
maxProcessorsIf a value greater than zero is specified, it is the maximum number of processors allowed, which takes precedence over the current limit set for this image (see the MaxProcessors() and SetMaxProcessors() member functions). If zero or a negative value is specified, it is ignored and the current MaxProcessors() limit is applied. The default value is zero.
overheadLimitPxThread overhead limit in pixels. The function will calculate the minimum number of pixel rows that a single thread can process, based on this value and on the specified rowWidth (or the image's width if zero is passed for that parameter). The default overhead limit is 1024 pixels.

This function takes into account if parallel processing is currently enabled for this image, as well as the maximum number of processors allowed for the calling process.

This function returns a dynamic array of unsigned integers, where each element is the number of pixel rows that the corresponding thread should process in order to make an optimal usage of the processor resources currently available. The length of the returned array is the maximum number of threads that the calling process should execute concurrently to process the specified number of pixel rows, with the specified overhead limit and maximum number of processors.

See also
Thread::OptimalThreadLoads()

Definition at line 944 of file AbstractImage.h.

References pcl::Max(), and pcl::Thread::OptimalThreadLoads().

◆ ParseChannel()

bool pcl::AbstractImage::ParseChannel ( int &  channel) const
inlinenoexcept

Interprets a channel index as a parameter to define a pixel sample selection.

Parameters
[in,out]channelIf a negative channel index is specified, this parameter will be replaced with the currently selected channel index in this image.

Returns true iff the output channel index is valid.

Definition at line 714 of file AbstractImage.h.

◆ ParseRect()

bool pcl::AbstractImage::ParseRect ( Rect rect) const
inlinenoexcept

Interprets the coordinates of a rectangle as a parameter to define a pixel selection.

Parameters
[in,out]rectIf this rectangle is empty (defining either a point or a line), this function sets it to the current rectangular selection in this image. If this rectangle is nonempty, this function constrains its coordinates to stay within image boundaries.

Returns true iff the output rectangle is nonempty.

Definition at line 691 of file AbstractImage.h.

◆ ParseSelection() [1/2]

bool pcl::AbstractImage::ParseSelection ( Rect rect,
int &  channel 
) const
inlinenoexcept

Interprets the coordinates of a rectangle and one channel index as parameters to define a pixel sample selection.

Parameters
[in,out]rectIf this rectangle is empty (defining either a point or a line), this function sets it to the current rectangular selection in this image. If this rectangle is nonempty, this function constrains its coordinates to stay within image boundaries.
[in,out]channelIf a negative channel index is specified, this parameter will be replaced with the currently selected channel index in this image.

Returns true iff the output rectangle is nonempty and the output channel index is valid.

Definition at line 789 of file AbstractImage.h.

◆ ParseSelection() [2/2]

bool pcl::AbstractImage::ParseSelection ( Rect rect,
int &  firstChannel,
int &  lastChannel 
) const
inlinenoexcept

Interprets the coordinates of a rectangle and two channel indexes as parameters to define a pixel sample selection.

Parameters
[in,out]rectIf this rectangle is empty (defining either a point or a line), this function sets it to the current rectangular selection in this image. If this rectangle is nonempty, this function constrains its coordinates to stay within image boundaries.
[in,out]firstChannelIf a negative channel index is specified, this parameter will be replaced with the first channel index of the current channel range selection in this image.
[in,out]lastChannelIf a negative channel index is specified, this parameter will be replaced with the last channel index of the current channel range selection in this image.

Returns true iff the output rectangle is nonempty and the output channel range is valid. When true is returned, this function ensures that firstChannellastChannel.

Definition at line 752 of file AbstractImage.h.

Referenced by pcl::GenericMatrix< T >::FromImage().

◆ PopSelections()

void pcl::AbstractImage::PopSelections ( ) const
inline

Restores and pops (removes) the current selections (rectangular area, channel range, anchor point and range clipping) from the internal selection stack.

If no selections have been previously pushed to the internal selection stack, this function is ignored.

Definition at line 659 of file AbstractImage.h.

◆ PushSelections()

void pcl::AbstractImage::PushSelections ( ) const
inline

Saves the current selections (rectangular area, channel range, anchor point and range clipping), pushing them to the internal selection stack.

Definition at line 646 of file AbstractImage.h.

◆ RangeClipHigh()

double pcl::AbstractImage::RangeClipHigh ( ) const
inlinenoexcept

Returns the upper bound of the current clipping range.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 550 of file AbstractImage.h.

◆ RangeClipLow()

double pcl::AbstractImage::RangeClipLow ( ) const
inlinenoexcept

Returns the lower bound of the current clipping range.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 540 of file AbstractImage.h.

◆ ResetChannelRange()

void pcl::AbstractImage::ResetChannelRange ( ) const
inlinenoexcept

Resets the channel range selection to include all existing channels (all nominal and alpha channels) in this image.

Definition at line 265 of file AbstractImage.h.

References pcl::Max().

◆ ResetPoint()

void pcl::AbstractImage::ResetPoint ( ) const
inlinenoexcept

Resets the anchor point to the origin of image coordinates, i.e to x=y=0.

Definition at line 330 of file AbstractImage.h.

◆ ResetRangeClipping()

void pcl::AbstractImage::ResetRangeClipping ( ) const
inlinenoexcept

Resets the range clipping parameters:

Clipping range lower bound = 0.0 Clipping range upper bound = 1.0 Range clipping disabled

Definition at line 601 of file AbstractImage.h.

◆ ResetSelection()

void pcl::AbstractImage::ResetSelection ( ) const
inlinenoexcept

Resets the rectangular selection to include the entire image boundaries.

Definition at line 387 of file AbstractImage.h.

◆ ResetSelections()

void pcl::AbstractImage::ResetSelections ( ) const
inlinenoexcept

Resets all image selections to default values:

  • All channels are selected, including nominal and alpha channels.
  • The anchor point is located at {0,0}, that is the upper left corner.
  • The rectangular selection is set to comprise the entire image.
  • The clipping range is set to [0,1].
  • Range clipping is disabled.

Calling this member function is equivalent to:

void ResetPoint() const noexcept
void ResetSelection() const noexcept
void ResetRangeClipping() const noexcept
void ResetChannelRange() const noexcept

Definition at line 626 of file AbstractImage.h.

◆ RunThreads()

template<class thread >
static void pcl::AbstractImage::RunThreads ( ReferenceArray< thread > &  threads,
ThreadData data,
bool  useAffinity = true 
)
inlinestatic

Runs a set of threads with synchronized status monitoring and task abortion.

Parameters
threadsReference to a ReferenceArray container of threads. ReferenceArray contains pointers to objects and allows direct iteration and access by reference. It cannot contain null pointers. Each ReferenceArray element must be an instance of a derived class of Thread, where a reimplemented Thread::Run() member function should perform the required parallel processing.
dataReference to a ThreadData object for synchronization.
useAffinityIf (1) this parameter is true, (2) the threads array contains two or more threads, and (3) this function is being called from the root thread (see Thread::IsRootThread()), then each thread will be run with its affinity set to a single processor (on systems that support thread processor affinity). If one or more of the three conditions above is false, the thread(s) will be run without forcing their processor affinities.

When the threads array contains more than one thread, this static member function launches the threads in sequence and waits until all threads have finished execution. While the threads are running, the status member of ThreadData is incremented regularly to perform the process monitoring task. This also ensures that the graphical interface remains responsive during the whole process.

When the threads array contains just one thread, this member function simply calls the Thread::Run() member function for the unique thread in the array, so no additional parallel execution is performed in the single-threaded case. If the reimplemented Thread::Run() member function uses standard PCL macros to perform the thread monitoring task (see the INIT_THREAD_MONITOR() and UPDATE_THREAD_MONITOR() macros), all possible situations will be handled correctly and automatically.

For normal execution of multiple concurrent threads with maximum performance, the useAffinity parameter should be true in order to minimize cache invalidations due to processor reassignments of running threads. However, there are cases where forcing processor affinities can be counterproductive. An example is real-time previewing of intensive processes requiring continuous GUI updates. In these cases, disabling processor affinity can help to keep the GUI responsive with the required granularity.

The threads can be aborted asynchronously with the standard Thread::Abort() mechanism, or through StatusMonitor/StatusCallback. If one or more threads are aborted, this function destroys all the threads by calling ReferenceArray::Destroy(), and then throws a ProcessAborted exception. In the single-threaded case, if the reimplemented Thread::Run() member function throws an exception, the array is also destroyed and the exception is thrown. Otherwise, if all threads complete execution normally, the threads array is left intact and the function returns. The caller is then responsible for destroying the threads when appropriate.

Warning
For parallel execution of two or more threads, do not call this function from a high-priority thread. Doing so can lead to a significant performance loss because this function will consume too much processing time just for process monitoring. In general, you should call this function from normal priority threads.

Definition at line 1072 of file AbstractImage.h.

References pcl::ReferenceArray< T, A >::Begin(), pcl::AbstractImage::ThreadData::count, pcl::ReferenceArray< T, A >::Destroy(), pcl::ReferenceArray< T, A >::End(), pcl::ReferenceArray< T, A >::IsEmpty(), pcl::Thread::IsRootThread(), pcl::ReferenceArray< T, A >::Length(), pcl::AbstractImage::ThreadData::mutex, pcl::AbstractImage::ThreadData::numThreads, pcl::StatusMonitor::RefreshRate(), pcl::AbstractImage::ThreadData::status, pcl::AbstractImage::ThreadData::total, pcl::Mutex::TryLock(), and pcl::Mutex::Unlock().

◆ SelectAlphaChannels()

void pcl::AbstractImage::SelectAlphaChannels ( ) const
inlinenoexcept

Sets the current channel range selection to include the existing alpha channels only, excluding the nominal channels.

Note
If this image has no alpha channels, this function selects the last nominal channel. The channel range selection cannot be empty by design.

Definition at line 254 of file AbstractImage.h.

References pcl::ColorSpace::NumberOfNominalChannels().

◆ SelectChannel()

void pcl::AbstractImage::SelectChannel ( int  c) const
inlinenoexcept

Selects a single channel.

Parameters
cChannel index, 0 ≤ c < n, where n is the total number of channels in this image, including alpha channels.

Definition at line 200 of file AbstractImage.h.

◆ SelectChannelRange()

void pcl::AbstractImage::SelectChannelRange ( int  c0,
int  c1 
) const
inlinenoexcept

Selects a range of channels by their channel indices. The selected range includes the two channels specified.

Parameters
c0Index of the first channel to select.
c1Index of the last channel to select.

Definition at line 227 of file AbstractImage.h.

◆ SelectedChannel()

int pcl::AbstractImage::SelectedChannel ( ) const
inlinenoexcept

Returns the index of the currently selected channel.

If the current channel selection includes more than one channel, this function returns the index of the first selected channel.

This function is a convenience synonym for FirstSelectedChannel().

Definition at line 215 of file AbstractImage.h.

◆ SelectedPoint()

const Point& pcl::AbstractImage::SelectedPoint ( ) const
inlinenoexcept

Returns the current anchor point.

Definition at line 338 of file AbstractImage.h.

◆ SelectedRectangle()

const Rect& pcl::AbstractImage::SelectedRectangle ( ) const
inlinenoexcept

Returns the current rectangular selection.

Definition at line 415 of file AbstractImage.h.

Referenced by pcl::ImageInfo::ImageInfo().

◆ Selections()

ImageSelections& pcl::AbstractImage::Selections ( ) const
inlinenoexcept

Returns a reference to the internal ImageSelections object in this image.

Definition at line 637 of file AbstractImage.h.

◆ SelectNominalChannels()

void pcl::AbstractImage::SelectNominalChannels ( ) const
inlinenoexcept

Sets the current channel range selection to include all nominal channels exclusively, excluding alpha channels.

Definition at line 240 of file AbstractImage.h.

References pcl::ColorSpace::NumberOfNominalChannels().

◆ SelectPoint() [1/2]

void pcl::AbstractImage::SelectPoint ( const Point p) const
inlinenoexcept

Selects a new anchor point p in image coordinates.

Definition at line 322 of file AbstractImage.h.

◆ SelectPoint() [2/2]

void pcl::AbstractImage::SelectPoint ( int  x,
int  y 
) const
inlinenoexcept

Selects an anchor point by its separate image coordinates.

Parameters
xHorizontal coordinate of the new anchor point.
yVertical coordinate of the new anchor point.

Definition at line 314 of file AbstractImage.h.

◆ SelectRectangle() [1/3]

void pcl::AbstractImage::SelectRectangle ( const Point p0,
const Point p1 
) const
inlinenoexcept

Defines the current rectangular selection by its separate corner points in image coordinates.

Parameters
p0Position of the upper left corner of the new selection.
p1Position of the lower right corner of the new selection.

Definition at line 370 of file AbstractImage.h.

◆ SelectRectangle() [2/3]

void pcl::AbstractImage::SelectRectangle ( const Rect r) const
inlinenoexcept

Defines the current rectangular selection as the specified rectangle r in image coordinates.

Definition at line 379 of file AbstractImage.h.

◆ SelectRectangle() [3/3]

void pcl::AbstractImage::SelectRectangle ( int  x0,
int  y0,
int  x1,
int  y1 
) const
inlinenoexcept

Defines the current rectangular selection by its separate image coordinates.

Parameters
x0,y0Upper left corner coordinates (horizontal, vertical) of the new rectangular selection.
x1,y1Lower right corner coordinates (horizontal, vertical) of the new rectangular selection.

The resulting selection is constrained to stay within the image boundaries.

Definition at line 356 of file AbstractImage.h.

◆ SetRangeClipHigh()

void pcl::AbstractImage::SetRangeClipHigh ( double  clipHigh) const
inlinenoexcept

Sets the upper bound of the clipping range.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 572 of file AbstractImage.h.

References pcl::Swap().

◆ SetRangeClipLow()

void pcl::AbstractImage::SetRangeClipLow ( double  clipLow) const
inlinenoexcept

Sets the lower bound of the clipping range.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 560 of file AbstractImage.h.

References pcl::Swap().

◆ SetRangeClipping()

void pcl::AbstractImage::SetRangeClipping ( double  clipLow,
double  clipHigh 
) const
inlinenoexcept

Sets the lower and upper bounds of the clipping range and enables range clipping (both low and high clipping bounds), in a single function call.

See IsRangeClippingEnabled() for more information on range clipping.

Definition at line 585 of file AbstractImage.h.

References pcl::Swap().

◆ SetStatusCallback()

void pcl::AbstractImage::SetStatusCallback ( pcl::StatusCallback callback) const
inlinenoexcept

Specifies the address of an object that will be used to perform status monitoring callbacks for this image.

Definition at line 828 of file AbstractImage.h.

◆ Status()

StatusMonitor& pcl::AbstractImage::Status ( ) const
inlinenoexcept

Returns a reference to the status monitoring object associated with this image.

Definition at line 800 of file AbstractImage.h.

◆ StatusCallback()

pcl::StatusCallback* pcl::AbstractImage::StatusCallback ( ) const
inlinenoexcept

Returns the address of the status monitoring callback object currently selected for this image.

Definition at line 809 of file AbstractImage.h.


The documentation for this class was generated from the following file: