3.1.10. Misc modules and functions¶
3.1.10.1. ¶
3.1.10.1.1. Description¶
Kernel generator using for multipurpose such as de-noising, filtering, local feature capturing, and etc. Advanced constructor tool applied for highly customized numerical computing. Or kernel related utilities.
Tensor kernel generator module in informatics. Location in info.toolbox.libs._basic. Also can import through
from info.me import kernel_utils.
kernel generator. |
|
generate an averaging kernel with specified shape. |
|
generate a Gaussian kernel from a multivariate gaussian distribution. |
|
generate a LoG kernel through multivariate gaussian distribution. |
|
generate a Gabor kernel via a harmonic sine multivariate gaussian distribution. |
3.1.10.1.2. Docstrings¶
- class KernelGen¶
kernel generator. available for numpy and cupy ndarray.
- Arguments:
- Parameters:
shape (tuple[int, ...]) – tuple for kernel shape
dtype (Type) – element type passed on numpy ndarray; int as default
buffer (Optional[Union[numpy.ndarray]]) – argument passed on numpy ndarray;
Noneas defaultoffset (Optional[int]) – argument passed on numpy ndarray; 0 as default
strides (Optional[tuple[int]]) – argument passed on numpy ndarray;
Noneas defaultorder (Literal['C', 'F']) – argument passed on numpy ndarray;
'C'for row-major and'F'for column-major;'C'as defaultorigin (Union[int, Iterable[int]]) – bias of kernel center; must be Iterable object of int to specify bias for each axis, or int assignment applied that bias to all axis; 0 as default
fill (Numeric) – int or float for filling all elements in Kernel; 1 as default
replace (Union[numpy.ndarray, cupy.ndarray]) – substituting element by customized ndarray if specified;
Noneas default
- Returns:
a ndarray kernel
- Return type:
- Properties:
- rela_anchor:
anchor coordinate relative to zero-origin anchor.
- center:
physical center of kernel.
- anchor:
anchor coordinate of kernel.
- anchor_id:
anchor index in raveled kernel.
- rela_pos_rv:
a raveled coordinates of all kernel elements relative to kernel center.
- Examples:
from info.me import kernel_utils as ku import numpy as np shape_ = (2, 3) avg_k = ku.KernelGen(shape=shape_, fill=1/np.prod(shape_))
- Logs:
Added in version 0.0.2.
– Created by Chen Zhang; Last updated on 01:34, 2025-09-06
- averaging_kernel¶
generate an averaging kernel with specified shape. available for numpy and cupy ndarray.
- Arguments:
- Parameters:
k_shape (tuple[int, ...]) – tuple for kernel shape
- Returns:
an averaging kernel
- Return type:
- Raises:
TypeError – argument
'k_shape'is not assigned properly
- Examples:
from info.me import kernel_utils as ku avg_k = ku.averaging_kernel(k_shape=(2, 3))
- See also:
- Logs:
Added in version 0.0.2.
– Created by Chen Zhang; Last updated on 01:34, 2025-09-06
- gaussian_kernel¶
generate a Gaussian kernel from a multivariate gaussian distribution. available for numpy and cupy ndarray.
- Arguments:
- Parameters:
k_shape (tuple[int, ...]) – tuple for kernel shape
k_mu (Union[numpy.ndarray, cupy.ndarray]) – mean of Gaussian; \(\boldsymbol{0}\) vector as default
k_sigma (Union[numpy.ndarray, cupy.ndarray]) – covariance matrix of Gaussian; diagonal matrix of
k_shapeas default
- Variables:
~other_info (bool) – whether return the other information about kernel;
Falseas default- Returns:
a Gaussian kernel object, and possibly the covariance \(\boldsymbol{\Sigma}\) and the corresponding rank \(r(\boldsymbol{\Sigma})\)
- Return type:
Union[KernelGen, tuple[KernelGen, list[Union[ndarray, int]]]]
- Raises:
TypeError – argument
k_shapeis not assigned properly
- Examples:
from info.me import kernel_utils as ku gs_k = ku.gaussian_kernel(k_shape=(2, 3))
- Notes:
The kernel generation uses Gaussian multivariate probability density function as follows:
(3.18)¶\[f(\boldsymbol{x}|\boldsymbol{\mu},\boldsymbol{\Sigma}) = \frac{1}{(2\pi)^{\frac{k}{2}} \vert \boldsymbol{\Sigma} \vert^{\frac{1}{2}}} \exp{[-\frac{1}{2} (\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})]}\]Where \(\boldsymbol{m}^T\boldsymbol{\Sigma}\boldsymbol{m} > 0\), for all \(\boldsymbol{m} \in \mathbb{R}^k\).
Internal variable
'~other_info'can be overwritten, default value usesFalse; ifTrue, the values of returned kernel will not be rescaled, and \(\boldsymbol{\Sigma}\) and \(\mathrm{r}(\boldsymbol{\Sigma})\) will be returned as well. here shows the demonstration:from info.me import kernel_utils as ku gs_k, other_info = ku.gaussian_kernel(k_shape=(2, 3), **{'~other_info': True})
Final effect of gaussian kernel showed with a 3-dimensional surface is showed as Figure 4.16.
- See also:
- Logs:
Added in version 0.0.2.
– Created by Chen Zhang; Last updated on 01:34, 2025-09-06
- laplacian_of_gaussian_kernel¶
generate a LoG kernel through multivariate gaussian distribution. available for numpy and cupy ndarray.
- Arguments:
- Parameters:
k_shape (tuple[int, ...]) – tuple for kernel shape
k_mu (Union[numpy.ndarray, cupy.ndarray]) – mean of Gaussian; \(\boldsymbol{0}\) vector as default
k_sigma (Union[numpy.ndarray, cupy.ndarray]) – covariance matrix of Gaussian; diagonal matrix of
k_shapeas default
- Returns:
an un-rescaled LoG kernel
- Return type:
- Raises:
TypeError – argument
k_shapeis not assigned properly
- Examples:
from info.me import kernel_utils as ku log_k = ku.laplacian_of_gaussian_kernel(k_shape=(2, 3))
- Notes:
The 1st order derivative of gaussian distribution Equation 3.18 are:
(3.19)¶\[\frac{\partial f(\boldsymbol{x}|\boldsymbol{\mu},\boldsymbol{\Sigma})}{\partial \boldsymbol{x}} = - \frac{\boldsymbol{\Sigma}^{-1}(\boldsymbol{x} - \boldsymbol{\mu})}{(2\pi)^\frac{k}{2} \vert \boldsymbol{\Sigma} \vert^\frac{1}{2}} \exp{[-\frac{1}{2} (\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})]} = - \boldsymbol{\Sigma}^{-1}(\boldsymbol{x} - \boldsymbol{\mu}) f(\boldsymbol{x}|\boldsymbol{\mu},\boldsymbol{\Sigma})\]And the derivative of 2nd order:
(3.20)¶\[\begin{split}\begin{eqnarray} \frac{\partial^2 f(\boldsymbol{x}|\boldsymbol{\mu},\boldsymbol{\Sigma})}{\partial \boldsymbol{x} \partial \boldsymbol{x}^T} &=& \frac{[\boldsymbol{\Sigma}^{-1}(\boldsymbol{x}-\boldsymbol{\mu})(\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} - \boldsymbol{\Sigma}^{-1}]}{(2\pi)^\frac{k}{2} \vert \boldsymbol{\Sigma} \vert^\frac{1}{2}} \exp{[-\frac{1}{2} (\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})]} \\ &=& [\boldsymbol{\Sigma}^{-1}(\boldsymbol{x} - \boldsymbol{\mu}) (\boldsymbol{x}-\boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} - \boldsymbol{\Sigma}^{-1}] f(\boldsymbol{x}|\boldsymbol{\mu},\boldsymbol{\Sigma}) \end{eqnarray}\end{split}\]Based on the definition of 2nd order gradient operator \(\nabla^2\), the Laplacian of Gaussian can be calculated through traces of each matrices in Equation 3.20 theoretically, however for simplification, generating its weights via the following kernel is much speedy and practical:
(3.21)¶\[f(\boldsymbol{x} | \boldsymbol{\mu}, \boldsymbol{\Sigma}) \propto [\frac{(\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})}{2} - 1] \exp{[-\frac{(\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})}{2}]}\]Where the \(\boldsymbol{\mu}\) denotes the geometric center of the kernel, for any \(\boldsymbol{m} \in \mathbb{R}^k\) (\(k\) is the number of dimensions), the \(\boldsymbol{\Sigma}\) must be positive definite (\(\boldsymbol{m}^T \boldsymbol{\Sigma} \boldsymbol{m} > 0\)).
In practice, info takes \(\boldsymbol{\mu} = \boldsymbol{0}\), and the kernel will be of the following form:
(3.22)¶\[\mathrm{LoG}(\boldsymbol{x} | \boldsymbol{0}, \boldsymbol{\Sigma}) = C_1 \cdot (1 - \boldsymbol{x}^T \boldsymbol{\Sigma_{d}^{-1}} \boldsymbol{x}) \exp{(- \boldsymbol{x}^T \boldsymbol{\Sigma_{d}^{-1}} \boldsymbol{x})} + C_2\]\(C_1\) and \(C_2\) are constants for scale and location respectively. \(\boldsymbol{0}\) and \(\boldsymbol{\Sigma}\) are parameters for Gaussian component in kernel. The sign of \(C_1\) determine how this kernel works: if \(\mathrm{sgn}(C_1) = 1\), it will perform as a 2nd-order differential operator to highlight the areas with high change rate in value (or edge-like areas in conventional description); if \(\mathrm{sgn}(C_1) = -1\), it will obtain a reversed the high change rate areas, with which overlapped into the original data the result will be revealed in higher contrast in edge-like areas.
Final effect of gaussian kernel showed with a 3-dimensional surface is showed as Figure 4.17.
- See also:
- Logs:
Added in version 0.0.2.
– Created by Chen Zhang; Last updated on 01:34, 2025-09-06
- gabor_kernel¶
generate a Gabor kernel via a harmonic sine multivariate gaussian distribution. available for numpy and cupy ndarray.
- Arguments:
- Parameters:
k_shape (tuple[int, ...]) – tuple for kernel shape
k_orientation (list[Numeric]) – spatial orientation where the harmonic sine function periodically repeats;
Noneas default to automatically generate 1 for each dimension (e.g.[1, 1, 1]for 3D data)k_rescale (Numeric) – rescale coefficient to determine the size of gaussian envelope; 1 as default
k_wavelength (Numeric) – wavelength of harmonic sine function; \(2\pi\) as default
k_phase (Numeric) – phase position of harmonic sine function; 0 as default
- Returns:
a complex number domain Gabor kernel object
- Return type:
- Raises:
TypeError – argument
k_shapeork_orientationis not assigned properly
- Examples:
from info.me import kernel_utils as ku gb_k = ku.gabor_kernel(k_shape=(10, 15), k_orientation=[1, 0.8])
- Notes:
The kernel generation uses multivariate gaussian, combined with spatial sine harmonic function as follows:
(3.23)¶\[G(\boldsymbol{x}|\boldsymbol{\mu}, \boldsymbol{\Sigma}, \boldsymbol{n}, A, \lambda, \phi) = A \cdot \exp{[-\frac{1}{2} (\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})]} \cdot \exp{[i(2\pi\frac{\boldsymbol{x}^T \boldsymbol{n} }{\lambda} + \phi)]}\]Where \(\boldsymbol{\mu}\) and \(\boldsymbol{\Sigma}\) are parameters in multivariate gaussian kernel. Generally, \(\boldsymbol{\mu} = \boldsymbol{0}\), and \(\boldsymbol{\Sigma}\) is automatically determined based on
k_shape. \(A\) refers amplitude for rescaling the gaussian envelope. \(\boldsymbol{n}\) is the normal direction for hyperplane of spatial sine (cosine) function (see note in spatial filtering), therefore, the scalar \(\boldsymbol{x} \cdot \boldsymbol{n}\) is the projection of \(\boldsymbol{x}\) in direction of \(\boldsymbol{n}\). \(\lambda\) and \(\phi\) is the wavelength and phase position for the spatial sine (cosine) function respectively.As the last item in Equation 3.23 is of the Euler’s formula, the \(G(\boldsymbol{x}|\boldsymbol{\mu}, \boldsymbol{\Sigma}, \boldsymbol{n}, A, \lambda, \phi)\) must be a complex kernel. More specifically, let \(N^\prime(\boldsymbol{x} | \boldsymbol{\mu}, \boldsymbol{\Sigma}) = \exp{[-\frac{1}{2} (\boldsymbol{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\boldsymbol{x} - \boldsymbol{\mu})]}\), the real part of Equation 3.23 will be:
(3.24)¶\[G_{\mathrm{rel}}(\boldsymbol{x}|\boldsymbol{\mu}, \boldsymbol{\Sigma}, \boldsymbol{n}, A, \lambda, \phi) = A \cdot N^\prime(\boldsymbol{x} | \boldsymbol{\mu}, \boldsymbol{\Sigma}) \cdot \cos{(2\pi \frac{\boldsymbol{x}^T \boldsymbol{n} }{\lambda} + \phi)}\]And for the imaginary part:
(3.25)¶\[G_{\mathrm{img}}(\boldsymbol{x}|\boldsymbol{\mu}, \boldsymbol{\Sigma}, \boldsymbol{n}, A, \lambda, \phi) = A \cdot N^\prime(\boldsymbol{x} | \boldsymbol{\mu}, \boldsymbol{\Sigma}) \cdot \sin{(2\pi \frac{\boldsymbol{x}^T \boldsymbol{n} }{\lambda} + \phi)}\]
- See also:
- Logs:
Added in version 0.0.4.
– Created by Chen Zhang; Last updated on 01:34, 2025-09-06
- Authors:
Chen Zhang
- Version:
0.0.5
- Created on:
Jun 28, 2023