# Utilities

## Available directions

The module `Directional`

computes correlation functions in many directions depending on how test line segments are aligned with the input array. The default directions are `[DirX()]`

for 1D, `[DirX(), DirY()]`

for 2D and `[DirX(), DirY(), DirZ()]`

for 3D arrays. Possible directions and their meaning are described below.

`CorrelationFunctions.Utilities.DirX`

— Type`DirX()`

A subtype of `AbstractDirection`

Corresponds to vectors `[1]`

, `[1, 0]`

or `[1, 0, 0]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirY`

— Type`DirY()`

A subtype of `AbstractDirection`

Corresponds to vectors `[0, 1]`

or `[0, 1, 0]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirZ`

— Type`CorrelationFunctions.Utilities.DirXY`

— Type`DirXY()`

A subtype of `AbstractDirection`

Corresponds to vectors `[1, 1]`

or `[1, 1, 0]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirYX`

— Type`DirYX()`

A subtype of `AbstractDirection`

Corresponds to vectors `[-1, 1]`

or `[-1, 1, 0]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirXZ`

— Type`DirXZ()`

A subtype of `AbstractDirection`

Corresponds to a vector `[1, 0, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirZX`

— Type`DirZX()`

A subtype of `AbstractDirection`

Corresponds to a vector `[-1, 0, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirYZ`

— Type`DirYZ()`

A subtype of `AbstractDirection`

Corresponds to a vector `[0, 1, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirZY`

— Type`DirZY()`

A subtype of `AbstractDirection`

Corresponds to a vector `[0, -1, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirXYZ`

— Type`DirXYZ()`

A subtype of `AbstractDirection`

Corresponds to a vector `[1, 1, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirXZY`

— Type`DirXZY()`

A subtype of `AbstractDirection`

Corresponds to a vector `[1, -1, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirYXZ`

— Type`DirYXZ()`

A subtype of `AbstractDirection`

Corresponds to a vector `[-1, 1, 1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.DirZYX`

— Type`DirZYX()`

A subtype of `AbstractDirection`

Corresponds to a vector `[1, 1, -1]`

.

See also: `AbstractDirection`

.

`CorrelationFunctions.Utilities.AbstractDirection`

— Type`AbstractDirection`

Abstract type for direction vectors used in calculation of directional correlation functions. Each subtype of `AbstractDirection`

corresponds with one 2D and/or one 3D vector along which slices are taken for calculation.

See also: `DirX`

, `DirY`

, `DirZ`

, `DirXY`

, `DirYX`

, `DirXZ`

, `DirZX`

, `DirYZ`

, `DirZY`

, `DirXYZ`

, `DirXZY`

, `DirYXZ`

, `DirZYX`

.

`CorrelationFunctions.Utilities.default_directions`

— Function`default_directions(array)`

Get default direction in which correlation functions are calculated for the given array.

The module `Map`

can use these types to extract directional information from correlation maps.

These rules can help you to memoize the correspondence between symbolic designations and vectors:

`DirFoo`

types can contain from one to three characters`X`

,`Y`

and`Z`

. Each character can occur only once (there is a type`DirXYZ`

, but no type`DirXXY`

).- When a character does not occur is a designation (e.g, there is no
`Z`

in`DirXY`

) that coordinate remains constant in a slice (in the example above $z = \text{const}$). - The names of the axes have a "natural order" which is
`X`

,`Y`

,`Z`

. In a designation the first axis which breaks that order get the minus sign in the direction vector (e.g.`DirXZY`

equals to`(1, -1, 1)`

because`Y`

is in the third position, not in the second,`DirZX`

equals to`(-1, 0, 1)`

because`X`

is in the second position, not in the first, etc.)

## Edge detection

The function `extract_edges`

complements `imfilter`

from `Images.jl`

and can be used to extract edges from an image on CPU and GPU.

`CorrelationFunctions.Utilities.extract_edges`

— Function`extract_edges(array, filter, topology)`

Perform edge extraction in the same way as in `surfsurf`

and `surfvoid`

functions from `Map`

and `Directional`

modules. `array`

may be a CUDA array or an ordinary array. `filter`

is a value of `AbstractKernel`

type which selects an edge extraction algorithm. Boundary conditions are affected by `topology`

. Periodic boundary conditions are assumed if `topology`

is `Torus()`

and reflection from the boundaries is used if `topology`

is `Plane()`

.

See also: `AbstractKernel`

, `AbstractTopology`

.

`CorrelationFunctions.Utilities.AbstractTopology`

— Type`CorrelationFunctions.Utilities.Plane`

— Type`Plane()`

Topology for calculation of correlation functions in non-periodic mode. Usually this means zero-padding of an input for out-of-bounds array access.

**NB**: When extracting edges with `Plane`

topology, reflection from array borders is used for out-of-bounds access. Although, it's natural to assume zero padding must be used, we want an equality $F_{ss}^{(false)} = F_{ss}^{(true)}$ for two-phase system, hence we cannot pad the input with some constant value.

See also: `AbstractTopology`

.

`CorrelationFunctions.Utilities.Torus`

— Type`Torus()`

Topology for calculation of correlation functions in periodic mode. An input is extended to the infinity periodically as if it was wrapped around a torus.

See also: `AbstractTopology`

.

`CorrelationFunctions.Utilities.AbstractKernel`

— Type`CorrelationFunctions.Utilities.ConvKernel`

— Type`ConvKernel(n)`

Convolution kernel of width `n`

used in edge detection. Values `5`

and `7`

are possible values for `n`

. Using `n = 7`

works best for the most cases (`lowfreq_energy_ratio(array) > 0.97`

).

See also: `AbstractKernel`

, `extract_edges`

.

`CorrelationFunctions.Utilities.ErosionKernel`

— Type`ErosionKernel(n)`

Erosion kernel of width `n`

used in edge detection. Used in three-point surface correlation functions.

See also: `AbstractKernel`

, `extract_edges`

.

## Misc

Some miscellaneous functions and helpers.

`CorrelationFunctions.Utilities.read_cuboid`

— Function`read_cuboid(datapath :: String, side, dim)`

Read 3D array from a disk. The data on the disk must be in binary format, one octet per sample. Totally, there must be $side^{dim}$ octets which are read into $side \times side \times \dots \times side$ array.

`CorrelationFunctions.Utilities.lowfreq_energy_ratio`

— Function`lowfreq_energy_ratio(array, fraction = 0.5)`

Calculate a ratio $E_a/E$ where $E$ is a total energy of a signal `array`

and $E_a$ is the energy concentrated in frequencies $[0, af/2]$ where $f$ is the sampling rate and $a$ is set via parameter `fraction`

. `mean(array)`

is subtracted from the array before calculations.

This function can be helpful in estimating if `array`

is suitable for calculating surface-surface or surface-void function. An empirical criterion is that if this function returns a value greater than `0.97`

, the array is good.

`CorrelationFunctions.Utilities.make_rotation`

— Function`make_rotation(ϕ)`

Make a rotation of 2-dimensional data by ϕ radians clockwise.

See also: `rotate_array`

.

`make_rotation(vec :: SVector{3}, ϕ)`

Make a rotation of 3-dimensional data by ϕ radians around a vector `vec`

clockwise.

See also: `rotate_array`

.

`make_rotation(m :: SMatrix{D,D})`

Make a rotation which transforms unit vectors to columns of `m`

. It is implicitly assumed that any two columns `c₁`

and `c₂`

have zero dot product: `(c₁, c₂) = 0`

and all columns are unit vectors.

`CorrelationFunctions.Utilities.rotate_array`

— Function`rotate_array(array, rot, topology)`

Rotate an array using rotation defined by `rot`

. The coordinate system's origin is placed into the center of the array. Out-of-bounds array access is specified by `topology`

argument. It is periodic extension of the array if `topology`

is `Torus()`

and zero padding if `topology`

is `Plane()`

.

See also: `AbstractTopology`

, `Torus`

, `Plane`

, `make_rotation`

.

`CorrelationFunctions.Utilities.detect_anisotropy`

— Function`detect_anisotropy(array, phase)`

Return a square matrix which characterizes anisotropy of the specified phase in the input. Each column of the matrix is a unit vector. The first vector points toward anisotropy and the other two vectors are perpendicular to the first vector and to each other. The resulting matrix can be used as an argument to `make_rotation`

.

See also: `rotate_array`

, `make_rotation`

.