The library infrastructure module

The nuts and bolts that make it all work

Modules

module Boundary
Handling image boundary extension for filtering
module Error management
Exception classes and error management functionality
module Frameworks
Functions that form the basis of most pixel-based processing in DIPlib.
module Image
The dip::Image class and types that provide a view into it.
module Iterators
Objects to iterate over images and image lines in different ways.
module Numeric algorithms and constants
Functions and constants to be used in numeric computation, unrelated to images.
module Overloading
Help with instantiating function templates and class templates for different pixel data types.
module Physical dimensions
Support for units, physical quantities and pixel sizes.
module Pixel data types
Types used for image samples (pixels), and related support functionality
module Random
Pseudo-random generator and probability distributions.
module Support types
Types used for image samples (pixels), and related support functionality

Namespaces

namespace dip::Option
Enumerated options are defined in the namespace dip::Option, unless they are specific to some other sub-namespace.
namespace dip
The dip namespace contains all the library functionality.

Classes

struct dip::LibraryInformation
Holds information about the DIPlib binary.
class dip::Graph
A non-directed, edge-weighted graph.
class dip::LowestCommonAncestorSolver
Solves the lowest common ancestor problem for a tree.
class dip::Kernel
Represents the shape and size of a filtering kernel.
class dip::Metric
Represents a metric to be used to create a dip::NeighborList
class dip::NeighborList
Defines the neighborhood of a pixel as a set of coordinates, with optionally their distance.
class dip::PixelTableOffsets
Represents an arbitrarily-shaped neighborhood (filter support) in an arbitrary number of dimensions.
class dip::PixelTable
Represents an arbitrarily-shaped neighborhood (filter support) in an arbitrary number of dimensions.
template<typename IndexType_, typename ValueType_, typename UnionFunction_>
class dip::UnionFind
An STL-like data structure for the union-find algorithm.
template<typename IndexType_>
class dip::SimpleUnionFind
A simplified version of dip::UnionFind that doesn’t store any information about the regions, only equivalences.

Functions

void dip::SetNumberOfThreads(dip::uint nThreads)
Sets the maximum number of threads to be using in computations.
auto dip::GetNumberOfThreads() -> dip::uint
Gets the maximum number of threads that can be used in computations.

Variables

dip::LibraryInformation const dip::libraryInformation
Constant that holds information about the DIPlib binary.

Macros

#define DIP_EXPORT
Indicates that the function or class is exported from the shared/dynamic-load library.
#define DIP_NO_EXPORT
Indicates that the function or class is not exported from the shared/dynamic-load library.
#define DIP_CLASS_EXPORT
Specifically for classes in a inheritance hierarchy and that must be passed across the executable/shared library interface.
#define DIP_NODISCARD
If your compiler supports it, adds [[nodiscard]] to a function definition.

Class documentation

struct dip::LibraryInformation
#include "diplib.h"

Holds information about the DIPlib binary.

Information in this structure can be used to display library information to the user (e.g. in a splash screen). It also contains information that can be used to determine at run time the properties of the DIPlib library that the application links to. Refer to dip::libraryInformation.

The string type starts either with “Release” or “Debug”, indicating the whether the library was compiled with optimizations enabled and no debug information (release) or without optimizations and with debug information (debug). Next it lists a series of compile-time options, separated by comma. The options are:

  • “with OpenMP”: indicates multithreading is built in.
  • “recording stack traces”: indicates that exceptions report a stack trace, rather than only show the function that threw it.
  • “asserts enabled”: indicates additional run-time tests for consistency are executed.
  • “Unicode support”: indicates e.g. units are output using Unicode.
  • “ICS support”: indicates ICS file reading and writing is available.
  • “TIFF support”: indicates TIFF file reading and writing is available.
  • “JPEG support”: indicates JPEG file reading and writing is available.
  • “PNG support”: indicates PNG file reading and writing is available.
Variables
dip::String name The library name
dip::String description A short description string
dip::String copyright Copyright string for the library
dip::String URL Library website, with contact information etc.
dip::String version The library version number
dip::String date Compilation date
dip::String type Describes options enabled during compilation

Function documentation

void dip::SetNumberOfThreads(dip::uint nThreads)

Sets the maximum number of threads to be using in computations.

The default maximum number of threads is given by the OMP_NUM_THREADS environment variable if set, or the number of CPU cores otherwise.

Note that parallelized algorithms only spawn multiple threads for the computation if the amount of work to be done is large enough to compensate for the overhead of spawning threads.

If nThreads is 1, disables multithreading within DIPlib. Usually it is more beneficial to manage multithreading at a higher level, for example by processing multiple images at the same time. If you do so, set nThreads to 1. Furthermore, it seems that calling multithreaded DIPlib functions from within an OpenMP parallel section doesn’t work, so within an OpenMP parallel section you should always set nThreads to 1.

If nThreads is 0, resets the maximum number of threads to the default value.

Note that this number is thread-local, meaning it only applies to the current thread from which this function is called. For every newly spawned thread, the maximum number of threads is the default as described above, not the value manually set prior to spawning the thread.

If DIPlib was compiled without OpenMP support, this function does nothing.

dip::uint dip::GetNumberOfThreads()

Gets the maximum number of threads that can be used in computations.

Returns the value given in the last call to dip::SetNumberOfThreads within the current thread, or the default maximum value if that function was never called within the current thread.

If DIPlib was compiled without OpenMP support, this function always returns 1.

Variable documentation

dip::LibraryInformation const dip::libraryInformation
#include "diplib.h"

Constant that holds information about the DIPlib binary.

Macro documentation

#define DIP_EXPORT
#include "diplib.h"

Indicates that the function or class is exported from the shared/dynamic-load library.

#define DIP_NO_EXPORT
#include "diplib.h"

Indicates that the function or class is not exported from the shared/dynamic-load library.

#define DIP_CLASS_EXPORT
#include "diplib.h"

Specifically for classes in a inheritance hierarchy and that must be passed across the executable/shared library interface.

Equal to DIP_NO_EXPORT on Windows and DIP_EXPORT elsewhere.

On Linux and other Unix-like systems, classes in a hierarchy, as well as classes thrown as exceptions, must be exported from the shared library if they are to be used across the interface between the library and whatever is using the library. This is the only way that the run-time linker is able to merge the virtual function tables, and identify the type of the thrown object.

However, on Windows, trying to export a class derived from a class in the standard library (such as std::exception), or trying to export a class that contains members of a non-exported class (such as a dip::String, a.k.a. std::string), causes compiler warnings. It seems that currently it is considered best practice to not export such classes. The Windows run-time linker always maps local classes to those in the shared library, even when they are not exported.

#define DIP_NODISCARD
#include "diplib.h"

If your compiler supports it, adds [[nodiscard]] to a function definition.

[[nodiscard]] will produce a compile-time warning if the function return value is discarded. This should pick up some programming errors, especially in cases where a different overload is picked by the compiler than expected by the programmer. For example:

dip::Mean( in, {}, out ); // OK, picks main function
out = dip::Mean( in );    // OK, picks alternate overload
dip::Mean( in, out );     // warns, picks alternate overload and output is discarded

The third line will warn because the compiler picks the dip::Mean( in, mask ) overload that returns the result image, rather than the intended main function dip::Mean( in, mask, out ) that puts the result in the existing out image.