Frame¶

Intuition¶

For an intuition on how this works, look at 2 Dimensional Classes documentation.

Example¶

We can load a frame from an image like so. We can then grab the np.ndarray using .data.

Note that most classes have a data property to grab the underlying data representation.

frame = Frame2D.from_image("path/to/file.jpg")
d = frame.data

Module Info¶

class frmodel.base.D2.frame2D.Frame2D(data: numpy.ndarray, labels: str)¶

Bases: frmodel.base.D2.frame._frame_loader._Frame2DLoader, frmodel.base.D2.frame._frame_partition._Frame2DPartition, frmodel.base.D2.frame._frame_channel._Frame2DChannel, frmodel.base.D2.frame._frame_scaling._Frame2DScaling, frmodel.base.D2.frame._frame_image._Frame2DImage, frmodel.base.D2.frame._frame_plot._Frame2DPlot, frmodel.base.D2.frame._frame_scoring._Frame2DScoring

A Frame is an alias to an Image.

The underlying representation is a 2D array, each cell is a array of channels

class CHN¶

Bases: frmodel.base.consts.CONSTS.CHN

This inherits the CONSTS CHN, nothing needs to be added here.

This makes it really easy to access the CONSTS without having to import it in.

e.g. f.CHN.XY

class GLCM¶: Bases: object

class KMEANS¶: Bases: object

class MNL¶: Bases: object

_BNDVI() → numpy.ndarray¶: Blue Normalized Difference Vegetation Index

_EX_G() → numpy.ndarray¶

Calculates the excessive green index

2g - 1r - 1b

_EX_GR() → numpy.ndarray¶

Calculates the excessive green minus excess red index

2g - r - b - 1.4r + g = 3g - 2.4r - b

Returns: np.ndarray, similar shape to callee. Use _get_chns to get as Frame2D

_GARI() → numpy.ndarray¶: Green Atmospherically Resistant Vegetation Index

_GBNDVI() → numpy.ndarray¶: Green Blue NDVI

_GLI() → numpy.ndarray¶: Green Leaf Index

_GNDVI() → numpy.ndarray¶: Green Normalized Difference Vegetation Index

_GRNDVI() → numpy.ndarray¶: Green Red NDVI

_HSV() → numpy.ndarray¶: Creates a HSV

_LCI() → numpy.ndarray¶: Leaf Chlorophyll Index

_MEX_G() → numpy.ndarray¶

Calculates the Modified excessive green index

1.262g - 0.884r - 0.331b

_MSAVI() → numpy.ndarray¶: Modified Soil Adjusted Vegetation Index

_NDI() → numpy.ndarray¶

Calculates the Normalized Difference Index

(g - r) / (g + r)

Returns: np.ndarray, similar shape to callee. Use _get_chns to get as Frame2D

_NDRE() → numpy.ndarray¶: Normalized Difference Red Edge

_NDVI() → numpy.ndarray¶: Normalized Difference Vegetation Index

_OSAVI() → numpy.ndarray¶: Optimized Soil Adjusted Vegetation Index

_VEG(const_a: float = 0.667) → numpy.ndarray¶

Calculates the Vegetative Index

g / {(r^a) * [b^(1 - a)]}

Parameters: const_a – Constant A depends on the camera used.
Returns: np.ndarray, similar shape to callee. Use _get_chns to get as Frame2D

_XY() → numpy.ndarray¶

Creates the XY Coord Array

Returns: np.ndarray, similar shape to callee. Use _get_chns to get as Frame2D

__init__(data: numpy.ndarray, labels: str)¶

Initializes the Frame2D with data

Note that because this is the __init__, reinitializing using a instance will not return anything.

If you need to initialize a class dynamically using an instance, use .create

Parameters

data – A Frame2D acceptable array, see Frame2D wiki for details
labels – Labels for the 2D array, it must be the same length as the data Channel Dimension

static _get_chn_size(chns: Iterable[frmodel.base.consts.CONSTS.CHN]) → int¶

This gets the channel size

That is, if you have [(R, G, B), X, H], this algorithm can flatten it can return 5.

_labels_to_ix(labels: str) → List[int]¶

Converts keys to indexes for splicing

Returns: np.ndarray, [A, B, C, …]

static _util_flatten(iterable)¶: Flattens potentially nested iterables

append(ar: numpy.ndarray, labels: str) → frmodel.base.D2.frame2D.Frame2D ¶

Appends another channel onto the Frame2D.

It is compulsory to include channel labels when appending. They can be arbitrary, however, the labels are used to easily extract the channel later.

It is recommended to use the consts provided in consts.py

Parameters

ar – The array to append to self array. Must be of the same dimensions for the first 2 axes
labels – A list of string labels. Must be the same length as the number of channels to append

Returns

Returns a new Frame2D, Shape = (Height, Width, Channel A + B)

convolute(radius: int) → Frame2D ¶

Convolutes the Frame, average per window

Parameters: radius – The radius of the convolution.

static create(data: numpy.ndarray, labels: dict) → frmodel.base.D2.frame2D.Frame2D ¶

This is an init function that allows you to receive the class upon initiation.

This function will not modify the caller as it’s static.

Parameters

data – A Frame2D acceptable array, see Frame2D wiki for details
labels – Labels for the 2D array, it must be the same length as the data Channel Dimension

crop(top: int = 0, right: int = 0, bottom: int = 0, left: int = 0) → frmodel.base.D2.frame._frame_image._Frame2DImage¶: Crops the frame by specifying how many rows/columns to remove from each side.

crop_glcm(glcm_radius: int, glcm_by: int = 1) → frmodel.base.D2.frame._frame_image._Frame2DImage¶: Crops the frame to match GLCM cropping.

data_chn(labels: Union[List, frmodel.base.consts.CONSTS.CHN, Any]) → frmodel.base.D2.frame2D.Frame2D ¶

Gets channels as another Frame2D

This will still return (Height, Width, 1) even on 1 channel, use squeeze to explicitly remove last dim

Parameters: labels – Can be a single str or multiple in a List
Returns: Frame2D, Shape=(Height, Width, Channels)

data_flatten_xy() → numpy.ndarray¶

Flattens the data on XY only.

This means that the first 2 dimensions will be merged together.

Returns: np.ndarray, Shape = (Height * Width, Channels)

data_kdtree(leaf_size=40, metric='minkowski', **kwargs) → sklearn.neighbors._kd_tree.KDTree¶

Constructs a KDTree with current data.

Uses sklearn.neighbours.KDTree API.

data_rgb() → frmodel.base.D2.frame2D.Frame2D ¶

Gets RGB as another Frame2D

Returns: Frame2D, Shape=(Height, Width, RGB Channels)

data_rgb_flatten() → numpy.ndarray¶

Flattens the RGB data by merging all RGB channels

The algorithm used is R + G * 256 + B * 256 * 256.

This is used to flatten the dimension while keeping all distinct values distinct.

Note the new dtype is uint32.

Returns: np.ndarray, Shape = (Height * Width)

classmethod from_image(file_path: str, scale: float = 1.0, scale_method=0) → Frame2D ¶

Creates an instance using the file path.

Parameters

file_path – Path to image
scale – The scaling to use
scale_method – The method of scaling. See Image.resize

Returns

Frame2D

classmethod from_nxy_(ar: numpy.ndarray, labels, xy_pos=(3, 4), width=None, height=None) → Frame2D ¶

Rebuilds the frame with XY values. XY should be of integer values, otherwise, will be casted.

Note that RGB channels SHOULD be on index 0, 1, 2 else some functions may break. However, can be ignored.

The frame will be rebuild and all data will be retained, including XY.

Parameters

ar – The array to rebuild
xy_pos – The positions of X and Y.
labels – The labels of the new Frame2D, excluding XY
height – Height of expected image, if None, Max will be used
width – Width of expected image, if None, Max will be used

Returns

Frame2D

get_chns(chns: Iterable[Frame2D.CHN, str] = ()) → Frame2D ¶

Gets selected channels

Use _get_all_chns to get all but selected ones

Parameters: chns – Channels, can be also in strings.
Returns Frame2D: Itself as a reference.

get_glcm(chns: Iterable[Frame2D.CHN] = (), radius: int = 2, bins: int = 8, step_size: int = 1, pairs: Tuple[str] = ('N', 'W', 'NW', 'SW'), scale_on_bands: bool = True)¶

This will get the GLCM statistics for this window

Details on how GLCM works is shown on the wiki.

Parameters

chns – Channels, can be also in strings.
radius – Radius of GLCM Window
bins – Bin size pre-processing of GLCM.
step_size – The step size of the window.

static labelize(ar: numpy.ndarray) → numpy.ndarray¶

Labelizes the np.ndarray.

This is used to make distinct values into categorical like value.

E.g. [[0, 10, 20], [10, 20, 34]] labelizes to [[0, 1, 2], [1, 2, 3]].

Note that if your array is >1D, all points of data will be treated equally due to flattening and the shape is preserved.

That is, [[A, B], [B, C]] will labelize as [[0, 1], [1, 2]] instead of [0, 1].

Parameters: ar – The array to labelize
Returns: An np.ndarray of the same shape

classmethod load(path: str, mask=True)¶

Loads the Frame2D from a .npz

Parameters

path – Path to the .npz
mask – To mask the array. This should be disabled if MemoryError occurs.

plot(labels: str = None) → frmodel.base.D2.frame._frame_plot.Frame2DPlot ¶

Gets a plot object. Note that you need to call a plot function to plot.

Parameters: labels – The labels to plot with.

save(path: str)¶

Saves the Frame2D underlying np.ndarray & dict as a .npz (.npy zip)

The recommended extension is .npz

scale_values(from_min=None, from_max=None, to_min=0, to_max=255) → Frame2D ¶

Linearly Scales data to another range. Modifies itself.

Parameters

from_min – The minimum, if none, data minimum will be used
from_max – The maximum, if none, data maximum will be used
to_min – The minimum to scale to (default 0)
to_max – The maximum to scale to (default 255)

Returns

self, the data will be modified internally regardless

scale_values_independent(from_min=None, from_max=None, to_min=0, to_max=255) → Frame2D ¶

Min Max Scales each channel to another range

Parameters

from_min – The minimum of each channel, if none, data minimum will be used
from_max – The maximum of each channel, if none, data maximum will be used
to_min – The minimum to scale to (default 0)
to_max – The maximum to scale to (default 255)

Returns

self, the data will be modified internally regardless

score(score_frame: Frame2D, label_ix: int = - 1, glcm_radius=None)¶

Scores the current frame kmeans with a scoring image

Parameters

label_ix – The label index to score against score_frame
score_frame – The score as Frame2D
glcm_radius – The radius of GLCM used if applicable. This will crop the Frame2D automatically to fit.

Returns

A Dictionary of various scoring algorithm results, {‘Custom’, ‘Homogeneity’, ‘Completeness’, ‘V Measure’}

static scorer_pair(predict: numpy.ndarray, actual: Frame2D)¶

A custom scoring algorithm. Called by score

Note that these parameters are non-reversible, that is scoring x against y is not the same as y against x.

y_frame, should be loaded in as RGB as it’ll go through an RGB distinct flatten, where every RGB value will be labelled distinctly.

Parameters

predict – Actual Labels. Must be a 1D label array
actual – Predict Frame. Can be either Frame with RGB or 1D label array

Returns

A Dictionary {score: float, score_pairs: np.ndarray of counts, labels: np.ndarray of labels}

size() → int¶: Returns the number of pixels, Height * Width.

view_blocks(height: int, width: int) → numpy.ndarray¶

Partitions the image into blocks using striding

Note that the height and width must be a divisor.

The dims are [RowBlock, ColBlock, Row, Col, Channels]

Parameters

height – Height of expected block, must be int divisor of original height
width – Width of expected block, must be int divisor of original width

view_blocks_as_frames(height: int, width: int) → List[List[Frame2D]]¶

Partitions the image into blocks using striding

Note that the height and width must be a divisor.

Parameters

height – Height of expected block, must be int divisor of original height
width – Width of expected block, must be int divisor of original width

view_windows(height: int, width: int, height_step: int, width_step: int) → numpy.ndarray¶

Partitions the image into windows using striding

Note that the parameters must cleanly divide the image else it’ll be cropped

E.g. 200 x 200 cannot be 100 Step 3 x 100 Step 7

The dims are [RowBlock, ColBlock, Row, Col, Channels]

Parameters

height – Height of expected window
width – Width of expected window
height_step – Step of height window
width_step – Step of width window

view_windows_as_frames(height: int, width: int, height_step: int, width_step: int) → List[List[Frame2D]]¶

Partitions the image into windows using striding

Note that the parameters must cleanly divide the image else it’ll be cropped

E.g. 200 x 200 cannot be 100 Step 3 x 100 Step 7

Parameters

height – Height of expected window
width – Width of expected window
height_step – Step of height window
width_step – Step of width window

property channels¶: Returns the channels as a list

property data¶

The underlying np.ndarray data.

Returns: np.ndarray, Shape = (Height, Width, Channels)

property dtype¶: Returns the dtype representation.

property labels¶

The dictionary of labels.

Returns: Dictionary, {‘NAME’(str): ix(int)}

property shape¶: Returns the Shape, similar to np.ndarray