corebreakout package

Submodules

corebreakout.column module

CoreColumn abstraction representing depth-registered single-column images of core material.

class corebreakout.column.CoreColumn(img, depths=None, top=None, base=None, add_tol=None, add_mode='fill')

Bases: object

Container for depth-registered, single-column images of core material.

These can be stacked with the __add__ operator, using add_mode from LHS instance, and padding the width of the narrower of (LHS.img, RHS.img) with zeros if necessary.

Either depths array or scalar top and base values must be provided to constructor.

add_mode
add_tol

Maximum allowed depth gap between columns when adding. Default is 2*dd.

dd

Median gap between adjacent depths.

depth_range

(self.top, self.base)

depths
img
iter_chunks(chunk_size, depths=True, step_size=None)

Generate data in chunk_size pieces, starting step_size apart.

If depths, yields (img, depths) of each chunk, else just img

TODO: make this able to fill partial last chunks.

classmethod load(path, name, **kwargs)

Load a CoreColumn instance from directory path.

If ‘<name>.pkl’ exists, will just load from that file.

Otherwise, at least ‘<name>_image.npy’ must exist. If ‘<name>_depths.npy’ also exists, those will be read as depths. If not, the user must pass either depths or top & base as **kwargs.

plot(figsize=(15, 50), tick_kwargs={}, major_kwargs={}, minor_kwargs={})

Make an image figure with major and minor depth ticks.

Parameters:
  • figsize (tuple(int)) – Size of matplotlib figure to plot on. Note: at default DPI of 100, 650 is about as large as common image formats will support saving (~2^16 pixels).
  • tick_kwargs – Parameters for tick creation: ‘major’ and ‘minor’ options for *_precision and *_format_str. See viz.make_depth_ticks().
  • major/minor_kwargs – Parameters for tick size and appearance. Passed to ax.tick_params.
Returns:

Matplotlib figure and axis with image + ticks plotted.
Return type:

fig, ax
save(path, name=None, pickle=True, image=False, depths=False)

Save the CoreColumn (or parts of it) to directory path.

Parameters:
  • path (str or Path) – Location to save to (must exist and be a directory).
  • name (str, optional) – Stem to save files as, default=`CoreColumn_<top>_<base>`.
  • pickle (bool, optional) – Whether to pickle the entire object with dill, default=True.
  • image (bool, optional) – Whether to save the image as ‘.npy’ file, default=False.
  • depths (bool, optional) – Whether to save the depths as a ‘.npy’ file, default=False
slice_depth(top=None, base=None)

Get a sliced CoreColumn between top and base, if it would have an effect and it is possible to do so.

corebreakout.defaults module

Default paths, dataset and Mask_RCNN model config, CoreColumn viz settings.

class corebreakout.defaults.DefaultConfig

Bases: mrcnn.config.Config

M-RCNN model configuration.

Override some default Mask_RCNN Config values.

For all available parameters and explanations, see:
https://github.com/matterport/Mask_RCNN/blob/master/mrcnn/config.py
BACKBONE = 'resnet101'
DETECTION_MAX_INSTANCES = 6
DETECTION_MIN_CONFIDENCE = 0.98
GPU_COUNT = 1
IMAGES_PER_GPU = 1
LOSS_WEIGHTS = {'mrcnn_bbox_loss': 1.0, 'mrcnn_class_loss': 0.5, 'mrcnn_mask_loss': 1.0, 'rpn_bbox_loss': 1.0, 'rpn_class_loss': 0.5}
NAME = 'cb_default'
NUM_CLASSES = 3
RPN_ANCHOR_RATIOS = [0.2, 0.5, 1]
RPN_ANCHOR_SCALES = (64, 128, 192, 256, 320)
RPN_NMS_THRESHOLD = 0.9
STEPS_PER_EPOCH = 25
VALIDATION_STEPS = 5

corebreakout.segmenter module

API for applying Mask R-CNN models to core sample images.

Mask R-CNN implementation from mrcnn package @ matterport/Mask_RCNN

A model_dir and weights_path are required to instantiate a CoreSegmenter

class corebreakout.segmenter.CoreSegmenter(model_dir, weights_path, model_config=<corebreakout.defaults.DefaultConfig object>, class_names=['col', 'tray'], layout_params={})

Bases: object

Mask R-CNN model container for extracting ``CoreColumn``s from core images.

Parameters:
  • model_dir (str or Path) – Path to directory containing saved mrcnn model(s)
  • weights_path (str or Path) – Path to saved weights file of the model
  • model_config (mrcnn.config.Config, optional) – Model configuration, default=``defaults.DefaultConfig()``.
  • class_names (list(str), optional) – A list of the class names for model output. Should be in same order as in the Dataset object that model was trained on. Default=`defaults.CLASSES`
  • layout_params (dict, optional) – Any layout parameters to override from default=`defaults.LAYOUT_PARAMS`. See docs/layout_parameters.md for explanations and options for each parameter.
static expected_tops_bases(depth_range, col_height)

Compute tops/bases of col_height columns spanning depth_range.

Note: col_bases[-1] does not necessarily == depth_range[-1]. The columns are meant to cover the range starting from top, not match it exactly.

Returns:
Return type:col_tops, col_bases
layout_params
segment(img, depth_range, add_tol=None, add_mode='fill', layout_params={}, show=False, colors=None)

Detect and segment core columns in img, return single aggregated CoreColumn instance.

Parameters:
  • img (str or array) – Filename or RGB image array to segment.
  • depth_range (list(float)) – Top and bottom depths of set of columns in image.
  • add_tol (float, optional) – Tolerance for adding discontinuous `CoreColumn`s. Default=None results in tolerance ~ image resolution.
  • add_mode (one of {‘fill’, ‘collapse’}, optional) – Add mode for generated CoreColumn instances (see CoreColumn docs)
  • layout_params (dict, optional) – Any layout parameters to override.
  • show (boolean, optional) – Set to True to show image with predictions overlayed.
  • colors (list, optional) – A list of RGBA tuples, one for each in class_names (excluding ‘BG’). Values should be in range [0.0, 1.0], If None, uses random colors. Has no effect unless show=True.
Returns:

img_col – Single aggregated CoreColumn instance
Return type:

CoreColumn
segment_all(imgs, depth_ranges, **kwargs)

Segment a set of imgs with known depth_ranges

Parameters:
  • imgs (Iterable) – Of either filepaths or image arrays.
  • depth_ranges (Iterable) – Of (top, base) depth pairs for each image.
  • **kwargs – See segment() docstring for options.
Returns:

img_col – Single aggregated CoreColumn instance
Return type:

CoreColumn

corebreakout.utils module

Assorted image / mask / label / region manipulation functions.

corebreakout.utils.crop_region(img, labels, region, axis=0, endpts=(815, 6775))

Adjust region bbox and return cropped region * mask.

Parameters:
  • img (array) – The image to crop
  • labels (array) – Mask of integer labels, same height and width as img
  • region (skimage.RegionProperties instance) – Region object corresponding to column to crop around
  • axis (int, optional) – Which axis to change endpts along, default=0 (y-coordinates)
  • endpts (tuple(int)) – Least extreme endpoint coordinates allowed along axis
Returns:

region – Masked image region, cropped in (adjusted) bounding box
Return type:

array
corebreakout.utils.masks_to_labels(masks)

Convert boolean (H,W,N) masks array to integer (H,W) in range(0,N+1).

corebreakout.utils.maximum_extent(regions, crop_axis)

Find min/max of combined skimage regions, along crop_axis.

corebreakout.utils.rotate_vertical(region_img, orientation)

Rotated (cropped) region_img array to vertical, given the depth orientation.

corebreakout.utils.sort_regions(regions, order)

Sort skimage regions (core columns), given the column order.

corebreakout.utils.squeeze_labels(labels)

Set labels to range(0, objects+1)

corebreakout.utils.strict_update(d1, d2)

For two dicts d1 and d2, works like d1.update(d2), except without adding any new keys to d1 (only values of existing keys updated).

Dictonaries are copied, so that this does not have an ‘inplace’ effect.

corebreakout.utils.vstack_images(imgA, imgB, *args)

Vstack imgA and imgB, after RHS zero-padding the narrower if necessary.

Will recursively add any additional images passed as *args.

corebreakout.viz module

Assorted visualization functions.

corebreakout.viz.draw_box(img, box, color, lw)

Draw 3-pixel width bounding boxes on the given image array. color: list of 3 int values for RGB.

corebreakout.viz.draw_lines(img, coords, axis, color=[255, 0, 0], lw=10)

Draw color lines on img at coords along axis.

axis == 0 –> horizonal lines axis == 1 –> vertical lines line width (lw) will round down to even numbers.

Raises:IndexError – If any (coord +/- (lw // 2)) falls outside of img
corebreakout.viz.local_min(arr, i)
corebreakout.viz.make_depth_ticks(depths, major_precision=0.1, major_format_str='{:.1f}', minor_precision=0.01, minor_format_str='{:.2f}')

Generate major & minor (ticks, locs) for depth array axis.

Parameters:
  • depths (array) – An array of (ordered) depth values from which to generate ticks/locs.
  • *_precision (float, optional) – Major, minor tick spacing (in depth units), defaults=0.1, 0.01.
  • *_format_str (str, optional) – Format strings to coerce depths -> tick strings, defaults=’{:.1f}’, ‘{:.2f}’.
Returns:

  • major_ticks, major_locs, minor_ticks, minor_locs
  • *_ticks (lists of tick label strings)
  • *_locs (lists of tick locations in array coordinates (fractional indices))
corebreakout.viz.show_preds(img, preds, class_names, colors=None, ax=None, figsize=(16, 16))

Less verbose wrapper for mrcnn.visualize.display_instances.

Parameters:
  • colors (list or array, optional) – Colors to use for each object in preds, default is random color for each.
  • ax (matplotlib axis, optional) – An axis to plot onto. If None, will create one with size figsize.

Module contents