Immutable regular-grid 2D adjacency with allocation-free traversal. More...

#include <RegularGridAdjacency2D.hpp>

Classes
class	GridIndexRangeT
	Small value range carrying one immutable traversal context. More...

class	IteratorAdjacencyT
	Allocation-free iterator over one independent grid traversal. More...

Public Types
using	IteratorAdjacency = IteratorAdjacencyT< false >
	Iterator over the complete stencil, including its configured origin.

using	ForwardIteratorAdjacency = IteratorAdjacencyT< true >
	Iterator over one directed half of the stencil.

using	AdjacentIndexRange = GridIndexRangeT< false, 0 >
	Range over adjacent indices including the origin.

using	NeighborIndexRange = GridIndexRangeT< false, 1 >
	Range over neighbouring indices excluding the origin.

using	ForwardNeighborIndexRange = GridIndexRangeT< true, 0 >
	Range over one directed half of the neighbouring indices.

Public Member Functions
	RegularGridAdjacency2D (int numRows, int numColumns, double radius)
	Builds an adjacency relation for a `numRows` by `numColumns` grid.

int	getSize () const noexcept
	Returns the number of offsets in the current stencil.

int	getNumRows () const noexcept
	Returns the number of rows in the attached grid domain.

int	getNumColumns () const noexcept
	Returns the number of columns in the attached grid domain.

RegularGridAdjacencyShape	getShape () const noexcept
	Returns how the immutable stencil was constructed.

bool	isAdjacent (PixelId p, PixelId q) const noexcept
	Tests adjacency between two linear grid indices.

bool	isAdjacent (int px, int py, int qx, int qy) const noexcept
	Tests adjacency between two grid coordinates.

double	getRadius () const noexcept
	Returns the configured or bounding Euclidean radius.

bool	is4connectivity () const noexcept
	Returns true when the stencil represents canonical 4-connectivity.

bool	is8connectivity () const noexcept
	Returns true when the stencil represents canonical 8-connectivity.

bool	isCanonical4Or8Connectivity () const noexcept
	Tests whether grid-topology formulas may interpret this as 4/8 connectivity.

bool	isGridBoundary (PixelId index) const
	Returns whether a linear grid index lies on the grid boundary.

bool	isGridBoundary (int row, int column) const noexcept
	Returns whether `(row, column)` lies on the grid boundary.

int	getOffsetRow (int index) const noexcept
	Returns the row offset stored at stencil position `index`.

int	getOffsetColumn (int index) const noexcept
	Returns the column offset stored at stencil position `index`.

AdjacentIndexRange	getAdjacentIndices (int row, int column) const
	Returns adjacent grid indices including the origin.

AdjacentIndexRange	getAdjacentIndices (PixelId gridIndex) const
	Returns adjacent grid indices including the origin.

NeighborIndexRange	getNeighborIndices (int row, int column) const
	Returns valid neighbouring grid indices excluding the origin.

NeighborIndexRange	getNeighborIndices (PixelId gridIndex) const
	Returns neighbouring grid indices excluding the origin.

ForwardNeighborIndexRange	getForwardNeighborIndices (int row, int column) const
	Returns the directed positive half of the neighbourhood.

ForwardNeighborIndexRange	getForwardNeighborIndices (PixelId gridIndex) const
	Returns the directed positive half of the neighbourhood.

Static Public Member Functions
static RegularGridAdjacency2D	fromStructuringElement (int numRows, int numColumns, std::span< const GridOffset2D > offsets)
	Builds adjacency induced by a symmetric structuring element.

static RegularGridAdjacency2D	rectangular (int numRows, int numColumns, int rowRadius, int columnRadius)
	Builds a centered rectangular structuring-element adjacency.

static RegularGridAdjacency2D	line (int numRows, int numColumns, int rowExtent, int columnExtent)
	Builds a centered digital line from `(-dr,-dc)` to `(dr,dc)`.

static RegularGridAdjacency2D	horizontalLine (int numRows, int numColumns, int halfLength)
	Builds a centered horizontal-line adjacency.

static RegularGridAdjacency2D	verticalLine (int numRows, int numColumns, int halfLength)
	Builds a centered vertical-line adjacency.

Friends
class	detail::CommittedGridAccess

Detailed Description

Immutable regular-grid 2D adjacency with allocation-free traversal.

RegularGridAdjacency2D stores a reusable stencil of offsets for a regular 2D image grid. The immutable stencil can be traversed either fully or in forward-only mode, which exposes only one directed half of the neighbourhood and is therefore convenient when unique undirected edges are needed.

Coordinates use (row, column) order. Linear grid indices use row * numColumns + column. Each traversal range owns its cursor state, so ranges over the same relation are reentrant and can be nested safely.

Definition at line 59 of file RegularGridAdjacency2D.hpp.

Member Typedef Documentation

◆ AdjacentIndexRange

using mmcfilters::RegularGridAdjacency2D::AdjacentIndexRange = GridIndexRangeT<false, 0>

Range over adjacent indices including the origin.

Definition at line 881 of file RegularGridAdjacency2D.hpp.

◆ ForwardIteratorAdjacency

using mmcfilters::RegularGridAdjacency2D::ForwardIteratorAdjacency = IteratorAdjacencyT<true>

Iterator over one directed half of the stencil.

Definition at line 830 of file RegularGridAdjacency2D.hpp.

◆ ForwardNeighborIndexRange

using mmcfilters::RegularGridAdjacency2D::ForwardNeighborIndexRange = GridIndexRangeT<true, 0>

Range over one directed half of the neighbouring indices.

Definition at line 885 of file RegularGridAdjacency2D.hpp.

◆ IteratorAdjacency

using mmcfilters::RegularGridAdjacency2D::IteratorAdjacency = IteratorAdjacencyT<false>

Iterator over the complete stencil, including its configured origin.

Definition at line 828 of file RegularGridAdjacency2D.hpp.

◆ NeighborIndexRange

using mmcfilters::RegularGridAdjacency2D::NeighborIndexRange = GridIndexRangeT<false, 1>

Range over neighbouring indices excluding the origin.

Definition at line 883 of file RegularGridAdjacency2D.hpp.

Constructor & Destructor Documentation

◆ RegularGridAdjacency2D()

mmcfilters::RegularGridAdjacency2D::RegularGridAdjacency2D	(	int	numRows,
		int	numColumns,
		double	radius
	)

inline

Builds an adjacency relation for a numRows by numColumns grid.

Parameters

numRows	Number of grid rows.
numColumns	Number of grid columns.
radius	Radius of the neighbourhood stencil. `1.0` gives 4-connectivity and `1.5` gives 8-connectivity on the integer grid.

Definition at line 275 of file RegularGridAdjacency2D.hpp.

Member Function Documentation

◆ fromStructuringElement()

static RegularGridAdjacency2D mmcfilters::RegularGridAdjacency2D::fromStructuringElement	(	int	numRows,
		int	numColumns,
		std::span< const GridOffset2D >	offsets
	)

inlinestatic

Builds adjacency induced by a symmetric structuring element.

The origin must appear exactly once and every (dr, dc) offset must have its opposite (-dr, -dc). This undirectedness contract is required by algorithms that traverse each grid edge once through getForwardNeighborIndices().

Parameters

numRows	Number of rows in the domain.
numColumns	Number of columns in the domain.
offsets	Symmetric structuring-element offsets.

Returns: The resulting adjacency induced by a symmetric structuring element.

Definition at line 415 of file RegularGridAdjacency2D.hpp.

◆ getAdjacentIndices() [1/2]

AdjacentIndexRange mmcfilters::RegularGridAdjacency2D::getAdjacentIndices	(	int	row,
		int	column
	)		const

inline

Returns adjacent grid indices including the origin.

Parameters

row	Zero-based row coordinate.
column	Zero-based column coordinate.

Returns: Adjacent grid indices including the origin.

Definition at line 894 of file RegularGridAdjacency2D.hpp.

◆ getAdjacentIndices() [2/2]

AdjacentIndexRange mmcfilters::RegularGridAdjacency2D::getAdjacentIndices ( PixelId gridIndex ) const

inline

Returns adjacent grid indices including the origin.

This overload accepts a validated row-major linear index.

Parameters

gridIndex Index.

Returns: Adjacent grid indices including the origin.

Definition at line 907 of file RegularGridAdjacency2D.hpp.

◆ getForwardNeighborIndices() [1/2]

ForwardNeighborIndexRange mmcfilters::RegularGridAdjacency2D::getForwardNeighborIndices	(	int	row,
		int	column
	)		const

inline

Returns the directed positive half of the neighbourhood.

Parameters

row	Zero-based row coordinate.
column	Zero-based column coordinate.

Returns: The directed positive half of the neighbourhood.

Definition at line 944 of file RegularGridAdjacency2D.hpp.

◆ getForwardNeighborIndices() [2/2]

ForwardNeighborIndexRange mmcfilters::RegularGridAdjacency2D::getForwardNeighborIndices ( PixelId gridIndex ) const

inline

Returns the directed positive half of the neighbourhood.

This overload accepts a validated row-major linear index.

Parameters

gridIndex Index.

Returns: The directed positive half of the neighbourhood.

Definition at line 957 of file RegularGridAdjacency2D.hpp.

◆ getNeighborIndices() [1/2]

NeighborIndexRange mmcfilters::RegularGridAdjacency2D::getNeighborIndices	(	int	row,
		int	column
	)		const

inline

Returns valid neighbouring grid indices excluding the origin.

Parameters

row	Zero-based row coordinate.
column	Zero-based column coordinate.

Returns: Valid neighbouring grid indices excluding the origin.

Definition at line 919 of file RegularGridAdjacency2D.hpp.

◆ getNeighborIndices() [2/2]

NeighborIndexRange mmcfilters::RegularGridAdjacency2D::getNeighborIndices ( PixelId gridIndex ) const

inline

Returns neighbouring grid indices excluding the origin.

This overload accepts a validated row-major linear index.

Parameters

gridIndex Index.

Returns: Neighbouring grid indices excluding the origin.

Definition at line 932 of file RegularGridAdjacency2D.hpp.

◆ getNumColumns()

int mmcfilters::RegularGridAdjacency2D::getNumColumns ( ) const

inlinenoexcept

Returns the number of columns in the attached grid domain.

Returns: The number of columns in the attached grid domain.

Definition at line 542 of file RegularGridAdjacency2D.hpp.

◆ getNumRows()

int mmcfilters::RegularGridAdjacency2D::getNumRows ( ) const

inlinenoexcept

Returns the number of rows in the attached grid domain.

Returns: The number of rows in the attached grid domain.

Definition at line 535 of file RegularGridAdjacency2D.hpp.

◆ getOffsetColumn()

int mmcfilters::RegularGridAdjacency2D::getOffsetColumn ( int index ) const

inlinenoexcept

Returns the column offset stored at stencil position index.

The method does not perform bounds checking.

Parameters

index Zero-based index.

Returns: The column offset stored at stencil position index.

Definition at line 681 of file RegularGridAdjacency2D.hpp.

◆ getOffsetRow()

int mmcfilters::RegularGridAdjacency2D::getOffsetRow ( int index ) const

inlinenoexcept

Returns the row offset stored at stencil position index.

The method does not perform bounds checking.

Parameters

index Zero-based index.

Returns: The row offset stored at stencil position index.

Definition at line 671 of file RegularGridAdjacency2D.hpp.

◆ getRadius()

double mmcfilters::RegularGridAdjacency2D::getRadius ( ) const

inlinenoexcept

Returns the configured or bounding Euclidean radius.

Radius-built relations preserve the original input radius. For a structuring element this is the maximum distance from its origin.

Returns: The configured or bounding Euclidean radius.

Definition at line 605 of file RegularGridAdjacency2D.hpp.

◆ getShape()

RegularGridAdjacencyShape mmcfilters::RegularGridAdjacency2D::getShape ( ) const

inlinenoexcept

Returns how the immutable stencil was constructed.

Returns: How the immutable stencil was constructed.

Definition at line 549 of file RegularGridAdjacency2D.hpp.

◆ getSize()

int mmcfilters::RegularGridAdjacency2D::getSize ( ) const

inlinenoexcept

Returns the number of offsets in the current stencil.

The count includes the central origin offset at stencil position 0.

Returns: The number of offsets in the current stencil.

Definition at line 528 of file RegularGridAdjacency2D.hpp.

◆ horizontalLine()

static RegularGridAdjacency2D mmcfilters::RegularGridAdjacency2D::horizontalLine	(	int	numRows,
		int	numColumns,
		int	halfLength
	)

inlinestatic

Builds a centered horizontal-line adjacency.

Parameters

numRows	Number of rows in the domain.
numColumns	Number of columns in the domain.
halfLength	Half-length of the centred line.

Returns: The resulting centered horizontal-line adjacency.

Definition at line 499 of file RegularGridAdjacency2D.hpp.

◆ is4connectivity()

bool mmcfilters::RegularGridAdjacency2D::is4connectivity ( ) const

inlinenoexcept

Returns true when the stencil represents canonical 4-connectivity.

Returns: True when the stencil represents canonical 4-connectivity.

Definition at line 612 of file RegularGridAdjacency2D.hpp.

◆ is8connectivity()

bool mmcfilters::RegularGridAdjacency2D::is8connectivity ( ) const

inlinenoexcept

Returns true when the stencil represents canonical 8-connectivity.

Returns: True when the stencil represents canonical 8-connectivity.

Definition at line 624 of file RegularGridAdjacency2D.hpp.

◆ isAdjacent() [1/2]

bool mmcfilters::RegularGridAdjacency2D::isAdjacent	(	int	px,
		int	py,
		int	qx,
		int	qy
	)		const

inlinenoexcept

Tests adjacency between two grid coordinates.

Coordinates are given as (x, y) pairs, where x is the column and y is the row. The method applies the configured stencil but does not check whether either coordinate lies inside the grid domain.

Parameters

px	Row coordinate of the first grid point.
py	Column coordinate of the first grid point.
qx	Row coordinate of the second grid point.
qy	Column coordinate of the second grid point.

Returns: True when the documented condition holds; otherwise false.

Definition at line 584 of file RegularGridAdjacency2D.hpp.

◆ isAdjacent() [2/2]

bool mmcfilters::RegularGridAdjacency2D::isAdjacent	(	PixelId	p,
		PixelId	q
	)		const

inlinenoexcept

Tests adjacency between two linear grid indices.

A grid index is adjacent to itself because every supported stencil includes the origin.

Parameters

p	Point.
q	Second point.

Returns: True when the documented condition holds; otherwise false.

Definition at line 561 of file RegularGridAdjacency2D.hpp.

◆ isCanonical4Or8Connectivity()

bool mmcfilters::RegularGridAdjacency2D::isCanonical4Or8Connectivity ( ) const

inlinenoexcept

Tests whether grid-topology formulas may interpret this as 4/8 connectivity.

Returns: True if grid-topology formulas may interpret this as 4/8 connectivity; otherwise false.

Definition at line 636 of file RegularGridAdjacency2D.hpp.

◆ isGridBoundary() [1/2]

bool mmcfilters::RegularGridAdjacency2D::isGridBoundary	(	int	row,
		int	column
	)		const

inlinenoexcept

Returns whether (row, column) lies on the grid boundary.

The method assumes coordinates are inside the grid domain.

Parameters

row	Zero-based row coordinate.
column	Zero-based column coordinate.

Returns: Whether (row, column) lies on the grid boundary.

Definition at line 661 of file RegularGridAdjacency2D.hpp.

◆ isGridBoundary() [2/2]

bool mmcfilters::RegularGridAdjacency2D::isGridBoundary ( PixelId index ) const

inline

Returns whether a linear grid index lies on the grid boundary.

The index is interpreted in row-major order. No explicit bounds check is performed before converting the index to (row, column).

Parameters

index Zero-based index.

Returns: Whether a linear grid index lies on the grid boundary.

Definition at line 647 of file RegularGridAdjacency2D.hpp.

◆ line()

static RegularGridAdjacency2D mmcfilters::RegularGridAdjacency2D::line	(	int	numRows,
		int	numColumns,
		int	rowExtent,
		int	columnExtent
	)

inlinestatic

Builds a centered digital line from (-dr,-dc) to (dr,dc).

Sampling follows the longest axis and rounds symmetrically, producing a centrally symmetric digital segment suitable as an undirected adjacency.

Parameters

numRows	Number of rows in the domain.
numColumns	Number of columns in the domain.
rowExtent	Vertical extent of the digital line.
columnExtent	Horizontal extent of the digital line.

Returns: The resulting centered digital line from (-dr,-dc) to (dr,dc).

Definition at line 461 of file RegularGridAdjacency2D.hpp.

◆ rectangular()

static RegularGridAdjacency2D mmcfilters::RegularGridAdjacency2D::rectangular	(	int	numRows,
		int	numColumns,
		int	rowRadius,
		int	columnRadius
	)

inlinestatic

Builds a centered rectangular structuring-element adjacency.

Parameters

numRows	Number of rows in the domain.
numColumns	Number of columns in the domain.
rowRadius	Vertical radius of the rectangular stencil.
columnRadius	Horizontal radius of the rectangular stencil.

Returns: The resulting centered rectangular structuring-element adjacency.

Definition at line 428 of file RegularGridAdjacency2D.hpp.

◆ verticalLine()

static RegularGridAdjacency2D mmcfilters::RegularGridAdjacency2D::verticalLine	(	int	numRows,
		int	numColumns,
		int	halfLength
	)

inlinestatic

Builds a centered vertical-line adjacency.

Parameters

numRows	Number of rows in the domain.
numColumns	Number of columns in the domain.
halfLength	Half-length of the centred line.

Returns: The resulting centered vertical-line adjacency.

Definition at line 514 of file RegularGridAdjacency2D.hpp.

Friends And Related Symbol Documentation

◆ detail::CommittedGridAccess

friend class detail::CommittedGridAccess

friend

Definition at line 61 of file RegularGridAdjacency2D.hpp.

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

mmcfilters/utils/RegularGridAdjacency2D.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ AdjacentIndexRange

◆ ForwardIteratorAdjacency

◆ ForwardNeighborIndexRange

◆ IteratorAdjacency

◆ NeighborIndexRange

Constructor & Destructor Documentation

◆ RegularGridAdjacency2D()

Member Function Documentation

◆ fromStructuringElement()

◆ getAdjacentIndices() [1/2]

◆ getAdjacentIndices() [2/2]

◆ getForwardNeighborIndices() [1/2]

◆ getForwardNeighborIndices() [2/2]

◆ getNeighborIndices() [1/2]

◆ getNeighborIndices() [2/2]

◆ getNumColumns()

◆ getNumRows()

◆ getOffsetColumn()

◆ getOffsetRow()

◆ getRadius()

◆ getShape()

◆ getSize()

◆ horizontalLine()

◆ is4connectivity()

◆ is8connectivity()

◆ isAdjacent() [1/2]

◆ isAdjacent() [2/2]

◆ isCanonical4Or8Connectivity()

◆ isGridBoundary() [1/2]

◆ isGridBoundary() [2/2]

◆ line()

◆ rectangular()

◆ verticalLine()

Friends And Related Symbol Documentation

◆ detail::CommittedGridAccess