hycore.templates

   1"""
   2Functions for creating and arranging template files to create various types of mosiacs.
   3"""
   4import hylite
   5from hylite import io
   6import numpy as np
   7import os
   8from pathlib import Path
   9from collections.abc import MutableMapping
  10
  11import hycore
  12
  13# the below code avoids occasional errors when running large templates
  14from PIL import Image, ImageFile
  15ImageFile.LOAD_TRUNCATED_IMAGES = True
  16
  17################################################################
  18## Labelling functions. These identify or flag parts of a core
  19## box or sample that are of interest during mosaicing
  20################################################################
  21def get_bounds(mask: hylite.HyImage, pad: int = 0):
  22    """
  23    Get the bounds of the foreground area in the given mask.
  24
  25    Args:
  26     - mask = A HyImage instance containing the foreground mask in the first band (background pixels flagged as 0 or False).
  27     - pad = Number of pixels padding to add to the masked area (N.B. this will not excede the image dimensions though).
  28
  29    Returns:
  30     - xmin,xmax,ymin,ymax = The bounding box of the foreground pixels.
  31    """
  32    if isinstance(mask, hylite.HyImage):
  33        mask = mask.data[..., 0]
  34    else:
  35        mask = mask.squeeze()
  36
  37    xmin = np.argmax(mask.any(axis=1))
  38    xmax = mask.shape[0] - np.argmax(mask.any(axis=1)[::-1])
  39    ymin = np.argmax(mask.any(axis=0))
  40    ymax = mask.shape[1] - np.argmax(mask.any(axis=0)[::-1])
  41
  42    if pad > 0:
  43        xmin = max(0, xmin - pad)
  44        xmax = min(mask.shape[0], xmax + pad)
  45        ymin = max(0, ymin - pad)
  46        ymax = min(mask.shape[1], ymax + pad)
  47
  48    return int(xmin), int(xmax), int(ymin), int(ymax)
  49
  50def get_breaks(mask: hylite.HyImage, axis: int = 0, thresh: float = 0.2):
  51    """
  52    Identify breaks in the foreground mask as local minima after summing in the specified axis.
  53
  54    Args:
  55     - axis = The axis along which to sum the mask before identifying minima.
  56     - thresh = the threshold used to define a "break", as a fraction of the maximum count (if a float is passed), or a specific value (if an int is past).
  57    """
  58    c = np.sum(mask.data[..., 0], axis=axis)
  59    if isinstance(thresh, float):
  60        thresh = np.max(c) * thresh
  61
  62    breaks = np.argwhere(np.diff((c > thresh).flatten(), axis=0)).flatten()
  63    if len(breaks) > 2:
  64        breaks = 0.5 * (breaks[2:][::2] + breaks[1:-1][::2])
  65        return breaks.astype(int)
  66    else:
  67        return []  # no breaks
  68
  69def label_sticks(mask: hylite.HyImage, axis: int = 0, thresh=0.2):
  70    """
  71    Identify and label sticks of core arranged in a box as follows:
  72
  73     -------------------
  74    |    stick 1      |
  75    |    stick 2      |
  76    |    stick 3      |
  77    -------------------
  78
  79    :param mask: A HyImage or numpy array containing 0s for all background and box pixels.
  80    :param axis: The long axis of each sticks. Default is 0 (x-axis).
  81    :param thresh: The threshold used to define breaks in the core (see get_breaks).
  82    :return: An updated mask with non-background pixels labelled according to their corresponding position
  83             in the core tray (from top to bottom if axis=0).
  84    """
  85
  86    # get bounds and breaks
  87    xmin, xmax, ymin, ymax = get_bounds(mask)
  88    breaks = get_breaks(mask, axis=axis, thresh=thresh)
  89
  90    # populate sticks
  91    idx = np.zeros((mask.xdim(), mask.ydim()))
  92    if axis == 0:
  93        steps = np.hstack([ymin, breaks, ymax])
  94
  95        # build stick template from each step
  96        for n, (i0, i1) in enumerate(zip(steps[:-1], steps[1:])):
  97            idx[:, int(i0):int(i1)] = n + 1
  98
  99    elif axis == 1:
 100        steps = np.hstack([xmin, breaks, xmax])
 101        for n, (i0, i1) in enumerate(zip(steps[:-1], steps[1:])):
 102            idx[int(i0):int(i1), :] = n + 1
 103
 104    else:
 105        assert False, "Error - axis should be 0 or 1, not %s" % axis
 106
 107    # intersect with mask
 108    idx[mask.data[..., 0] == 0] = 0
 109
 110    return hylite.HyImage(idx)
 111
 112def label_blocks(mask: hylite.HyImage):
 113    """
 114    Identify and label contiguous blocks. Useful for e.g. extracting samples or scanned thick-section blocks.
 115    :param mask: A HyImage or numpy array containing 0s for all background and box pixels.
 116    :return: An updated mask with non-background pixels labelled according to the contiguous block they belong to.
 117    """
 118
 119    from skimage.measure import label
 120    return hylite.HyImage(label(mask.data[..., 0]))
 121
 122################################################################
 123## Unwrap functions: These construct HyImage instances containing
 124## pixel mappings, that can be used to construct Templates
 125################################################################
 126def unwrap_bounds(mask: hylite.HyImage, *, pad: int = 1):
 127    """
 128    Construct and index template containing a mapping that just clips data to the mask (with the specified padding)
 129
 130    :param mask: The mask that defines the clipping operation.
 131    :param pad: Any padding (in pixels) to apply to this. Default is 1.
 132    :return: A HyImage instance with a clipped shape and containing the x,y coordinates of the source pixels (for creating a template).
 133    """
 134
 135    # get bounds and build indices
 136    xmn, xmx, ymn, ymx = get_bounds(mask, pad=pad)
 137    yy, xx = np.meshgrid(np.arange(mask.ydim()), np.arange(mask.xdim()))  # build coordinate arrays
 138    xy = np.dstack([xx, yy])
 139    xy[mask.data[..., 0] == 0, :] = -1
 140    idx = xy[xmn:xmx, ymn:ymx]
 141    return hylite.HyImage(idx)
 142
 143
 144def unwrap_tray(mask: hylite.HyImage, method='sticks', axis=0,
 145                flipx=False, flipy=False,
 146                thresh: float = 0.2,
 147                pad: int = 5, from_depth=0, to_depth=1):
 148    """
 149    Create a template that splits a core tray into individual "sticks"
 150    and then lays them end to end:
 151
 152    -------------------
 153    |    stick 1      |            ---------------------------
 154    |    stick 2      |       ==> | stick 1  stick 2  stick 3 |   if axis = 0
 155    |    stick 3      |            ---------------------------
 156    -------------------
 157
 158    or
 159
 160     -------------------
 161    |    stick 1      |            ----------
 162    |    stick 2      |       ==> | stick 1 |
 163    |                 |           | stick 2 |  if axis = 1
 164    |                 |           | stick 3 |
 165    |    stick 3      |            ----------
 166    -------------------
 167
 168
 169    :param mask: A HyImage instance containing 0s for all background and box pixels.
 170    :param method: The unwrapping method to use. Default is 'sticks' (see above), although 'blocks' is also possible
 171                    (label_blocks will be used instead of label_sticks).
 172    :param axis: The axis to stack the unwrapped segments along.
 173    :param flipx: True if the sticks should be ordered from right-to-left.
 174    :param flipy: True if the sticks should be ordered from bottom-to-top.
 175    :param thresh: The threshold used to define breaks in the core (see get_breaks). Default is 20% of the max count.
 176    :param pad: Number of pixels to include between sticks and on the edge of the image.
 177    :param from_depth: The depth of the start of this core box, for creating depth ticks. Default is 0. Tick positions and depth values will be stored in the resulting image's header.
 178    :param to_depth: The depth of the end of this core box, for creating depth ticks. Default is 1. Tick positions and depth values will be stored in the resulting image's header.
 179    :return: A HyImage instance containing the x,y coordinates of the unwrapped sticks.
 180    """
 181    if 'sticks' in method.lower():
 182        sticks = label_sticks(mask, axis=0, thresh=thresh)
 183    else:
 184        sticks = label_blocks(mask)
 185
 186    yy, xx = np.meshgrid(np.arange(mask.ydim()), np.arange(mask.xdim()))  # build coordinate arrays
 187    xy = np.dstack([xx, yy])
 188
 189    # extract chunks
 190    chunks = []
 191    for i in np.arange(1, np.max(sticks.data) + 1):
 192        msk = sticks.data[..., 0] == i  # get this segment
 193        xmn, xmx, ymn, ymx = get_bounds(msk, pad=pad)  # find its bounds
 194        idx = xy[xmn:xmx, ymn:ymx, :]  # get indices
 195        idx[~msk[xmn:xmx, ymn:ymx]] = -1  # also transfer background pixels
 196        chunks.append(xy[xmn:xmx, ymn:ymx, :])  # and store
 197
 198    # stack chunks
 199    if axis == 0:
 200        xdim = np.sum([c.shape[0] for c in chunks])
 201        ydim = np.max([c.shape[1] for c in chunks])
 202    else:
 203        xdim = np.max([c.shape[0] for c in chunks])
 204        ydim = np.sum([c.shape[1] for c in chunks])
 205
 206    idx = np.full((xdim, ydim, 2), -1, dtype=int)
 207    _o = 0
 208    ticks = []  # also store depth markers (ticks)
 209    depths = []  # and corresponding hole depths
 210    if flipy:
 211        chunks = chunks[::-1] # loop through chunks from bottom to top
 212    for i, c in enumerate(chunks):
 213        if flipx:
 214            c = c[::-1, :] # core runs right to left
 215        if axis == 0:
 216            idx[_o:(_o + c.shape[0]), 0:c.shape[1], :] = c
 217            ticks.append(_o)
 218            _o += c.shape[0]
 219        else:
 220            idx[0:c.shape[0], _o:(_o + c.shape[1]), :] = c
 221            ticks.append(_o + int(c.shape[1] / 2))
 222            _o += c.shape[1]
 223        depths.append(round(from_depth + i * (to_depth - from_depth) / len(chunks), 2))
 224
 225    out = hylite.HyImage(idx)
 226    out.header['depths'] = depths
 227    out.header['ticks'] = ticks
 228    out.header['tickAxis'] = axis
 229    return out
 230
 231################################################################
 232## Template factory
 233## These functions create templates for sets of boxes.
 234################################################################
 235def buildStack(boxes: hycore.Box, *, pad=1, axis=0, transpose=False):
 236    """
 237    Build a simple template that stacks data horizontally or vertically
 238
 239    :param boxes: A list of Box objects to stack.
 240    :param pad: Padding to add between boxes. Default is 1.
 241    :param axis: 0 to stack horizontally, 1 to stack vertically.
 242    :param transpose: If True, templates are transposed before stacking.
 243    :return: A template object containing the stacked indices.
 244    """
 245
 246    # get shed directory
 247    templates = []
 248    for b in boxes:
 249        try:
 250            mask = b.mask
 251        except:
 252            assert False, "Error - box %s must have a mask defined for it to be included in the stack" % b.name
 253
 254        # get clip index and construct template
 255        iClip = unwrap_bounds(mask, pad=pad)
 256        if transpose:
 257            iClip.data = np.transpose(iClip.data, (1, 0, 2))
 258
 259        templates.append(Template(b.getDirectory(), iClip,
 260                                  from_depth = b.start, to_depth = b.end,
 261                                  groups=[b.name], group_ticks=[iClip.xdim() / 2 ]))
 262
 263    # do stack
 264    return Template.stack(templates, axis=axis )
 265
 266################################################################
 267## Templates and Canvas classes encapsulate
 268## mosaicing transformations and can be used to push data around
 269## to derive mosaic images.
 270################################################################
 271
 272def compositeStack(template, images : list, bands : list = [(0, 1, 2)], *, axis=1, vmin=2, vmax=98, **kwargs):
 273    """
 274    Pass multiple images through the provided template and then stack the results along the specified axis.
 275
 276    :param template: The Template object to use to define mapping between output images and input images.
 277    :param images: A list of image names to resolve. If a single image is passed then this function reduces to be equivalent
 278                    to Template.apply( ... ).
 279    :param axis: The axis to stack the resulting output images along. Default is 1 (stack vertically along the y-axis).
 280    :param bands: A list of tuples defining the bands to be visualised for each image listed in `images`. These tuples
 281                  must have matching lengths!
 282    :param vmin: Percentile clip to apply separately to each dataset before doing stacking. Set as None to disable.
 283    :param vmax: Percentile clip to apply separately to each dataset before doing stacking. Set as None to disable.
 284    :param kwargs: All keyword arguments are passed to Template.apply
 285    :return: A composited and stacked image.
 286    """
 287
 288    # apply template to all input images
 289    I = []
 290    if not isinstance(bands, list): # allow people to pass e.g., (0,1,2) bands and have this extended
 291        bands = [bands] * len(images) # for each image.
 292    for i, b in zip(images, bands):
 293        I.append( template.apply(i, b, **kwargs) )
 294        if (vmin is not None):
 295            I[-1].percent_clip( vmin, vmax )
 296
 297    # stack results
 298    out = I[0]
 299    h = out.data.shape[axis]
 300    out.data = np.concatenate([i.data for i in I], axis=axis)
 301
 302    # add some metadata that can be useful for later plotting
 303    out.header['images'] = images
 304    out.header['bands'] = bands
 305    out.header['image_ticks'] = [i*h + 0.5 * h for i in range(len(images))]
 306    out.set_wavelengths(None) # remove wavelength info as this is invalid
 307
 308    # return
 309    return out
 310
 311class Template(object):
 312    """
 313    A special type of image dataset that stores drillcore, box and pixel IDs such that data from
 314    multiple sources can be re-arranged and combined into mosaick images.
 315    """
 316
 317    def __init__(self, boxes: list, index: np.ndarray, from_depth : float = None, to_depth : float = None,
 318                 groups=None, group_ticks=None, depths=None, depth_ticks=None, depth_axis=0):
 319        """
 320        Create a new Template instance.
 321        :param boxes: A list of paths for each box directory that is included in this template.
 322        :param index: An index array defining where data for index[x,y] should be sourced from. This should have four
 323                        bands specifying the: holeID (index in holes list), boxID (index in boxes list), xcoord (in source
 324                        image) and ycoord (in source image).
 325        :param from_depth: The top (smallest depth) of this template.
 326        :param to_depth: The bottom (largest depth) of this template.
 327        :param groups: Group names (e.g., boreholes) in this template.
 328        :param group_ticks: Pixel coordinates of ticks for these groups.
 329        :param depths: Depth values for ticks in the depth direction.
 330        :param depth_ticks: Pixel coordinates of the ticks corresponding to these depth values.
 331        :param depth_axis: Axis of this template that depth ticks correspond to.
 332        """
 333
 334        # check data types
 335        if isinstance(index, hylite.HyImage):
 336            index = index.data
 337        if isinstance(boxes, str) or isinstance(boxes, Path):
 338            boxes = [boxes]  # wrap in a list
 339
 340        # get root path and express everything as relative to that
 341        root = os.path.commonpath(boxes)
 342        if root == boxes[0]: # only one box (or all the same)
 343            root = os.path.dirname(boxes[0])
 344            self.boxes = [os.path.basename(b) for b in boxes]
 345        else:
 346            self.boxes = [os.path.relpath(b, root) for b in boxes]
 347
 348        for b in self.boxes:
 349            assert os.path.exists(os.path.join(root, b)), "Error box %s does not exist." % os.path.join(root, b)
 350
 351        # check dimensionality of index
 352        if index.shape[-1] == 2:
 353            index = np.dstack([np.zeros((index.shape[0], index.shape[1]), dtype=int), index])
 354
 355        assert index.shape[-1] == 3, "Error - index must have 3 bands (box_index, xcoord, ycoord)"
 356
 357        self.root = str(root)
 358        self.index = index.astype(int)
 359
 360        if (from_depth is not None) and (to_depth is not None):
 361            self.from_depth = min( from_depth, to_depth)
 362            self.to_depth = max( from_depth, to_depth )
 363            self.center_depth = 0.5*(from_depth + to_depth)
 364        else:
 365            self.center_depth = None
 366            self.from_depth = None
 367            self.to_depth = None
 368
 369        self.groups = None
 370        self.group_ticks = None
 371        self.depths = None
 372        self.depth_ticks = None
 373        self.depth_axis = depth_axis
 374
 375        if groups is not None:
 376            self.groups = np.array(groups)
 377        if group_ticks is not None:
 378            self.group_ticks = np.array(group_ticks)
 379        if depths is not None:
 380            self.depths = np.array(depths)
 381        if depth_ticks is not None:
 382            self.depth_ticks = np.array(depth_ticks)
 383
 384    def apply(self, imageName, bands=None, strict=False, xstep : int = 1, ystep : int = 1, scale : float = 1,
 385                    outline=None):
 386        """
 387        Apply this template to the specified dataset in each box.
 388
 389        :param imageName: The name of the image file to extract data from in each box, e.g., 'FENIX'.
 390        :param bands: The bands to export from the source image. Default is None (export all bands). See HyData.export_bands for possible formats.
 391        :param strict: If False (default), skip files that could not be found.
 392        :param xstep: Step to use in the x-direction. Useful for skipping pixels in the source image when building large mosaics.
 393        :param ystep: Step to use in the y-direction. Useful for skipping pixels in the source image when building large mosaics.
 394        :param scale: Scale factor to apply to pixel coordinates in this mosaic. Used for applying to images that are different resolutions.
 395        :param outline: Tuple containing the colour used to outline masked areas, or None to disable.
 396        :return: A HyImage instance containing the mosaic populated with the requested bands.
 397        """
 398        out = None
 399        for i, box in enumerate(self.boxes):
 400
 401            # get this box
 402            path = os.path.join( self.root, box )
 403            if strict:
 404                assert os.path.exists(path), "Error - could not load data from %d"
 405
 406            # load the required data
 407            try:
 408                try:
 409                    if '.' in imageName:
 410                        data = io.load(os.path.join(path, imageName) ) # extension is provided
 411                    else:
 412                        data = io.load(path).get(imageName) # look in box directory
 413                except (AttributeError, AssertionError) as e:
 414                    try:
 415                        if '.' in imageName:
 416                            data = io.load(os.path.join(path, 'results.hyc/%s'%imageName))  # extension is provided
 417                        else:
 418                            data = io.load(path).results.get(imageName) # look in results directory
 419                    except:
 420                        if strict:
 421                            assert False, "Error - could not find data %s in directory %s" % (imageName, path)
 422                        else:
 423                            continue
 424
 425                data.decompress()
 426            except (AttributeError, AssertionError) as e:
 427                if strict:
 428                    assert False, "Error - could not find data %s in directory %s" % (imageName, path )
 429                else:
 430                    continue
 431
 432            # get index and subsample as needed
 433            index = self.index[::xstep, ::ystep]
 434            if scale != 1:
 435                index = (index * scale).astype(int) # scale coordinates
 436                index[...,0] = self.index[::xstep, ::ystep, 0] # don't scale box IDs
 437
 438            # create output array
 439            if bands is not None:
 440                data = data.export_bands(bands)
 441            if out is None:
 442                # initialise output array now we know how many bands we're dealing with
 443                out = np.zeros( (index.shape[0], index.shape[1], data.band_count() ), dtype=data.data.dtype )
 444
 445            # copy data as defined in index array
 446            mask = (index[..., 0] == i) & (index[..., -1] != -1 )
 447            if mask.any():
 448                out[ mask, : ] = data.data[ index[mask, 1], index[mask, 2], : ]
 449        if len( data.get_wavelengths() ) != data.band_count():
 450            data.set_wavelengths(np.arange(data.band_count()))
 451
 452        # return a hyimage
 453        out = hylite.HyImage( out, wav=data.get_wavelengths() )
 454        if data.has_band_names():
 455            if len(data.get_band_names()) == out.band_count(): # sometimes this is not the case if we load a PNG with a header from a .dat file!
 456                out.set_band_names(data.get_band_names())
 457
 458        if (self.groups is not None) and (len(self.groups) > 0):
 459            out.header['groups'] = self.groups
 460        if (self.group_ticks is not None) and (len(self.group_ticks) > 0):
 461            out.header['group ticks'] = self.group_ticks
 462
 463        if outline is not None:
 464            self.add_outlines(out, color=outline, xx = xstep, yy = ystep )
 465        return out
 466
 467    def quick_plot(self, band=0, rot=False, xx=1, yy=1, interval=5, **kwds):
 468        """
 469        Quickly plot this template for QAQC.
 470        :param band: The band(s) to plot. Default is 0 (plot only box ID).
 471        :param rot: True if the template should be rotated 90 degrees before plotting.
 472        :param xx: subsampling in the x-direction (useful for large templates!). Default is 1 (no subsampling).
 473        :param yy: subsampling in the y-direction (useful for large templates!). Default is 1 (no subsampling).
 474        :param interval: Interval between depth ticks to add to plot.
 475        :keywords: Keywords are passed to hylite.HyImage.quick_plot( ... ).
 476        :return: fig,ax from the matplotlib figure created.
 477        """
 478        img = self.toImage()
 479        img.data = img.data[ ::xx, ::yy, : ]
 480        if rot:
 481            img.rot90()
 482        fig, ax = img.quick_plot(band, tscale=True, **kwds )
 483        self.add_ticks(ax, rot=rot, xx=xx, yy=yy, interval=interval)
 484        return fig, ax
 485
 486    def add_ticks(self, ax, interval=5, *, depth_ticks: bool = True, group_ticks: bool = True, rot: bool = False,
 487                  xx: int = 1, yy: int = 1, angle: float = 45):
 488        """
 489        Add depth and or group ticks (as stored in this template) to a matplotlib plot.
 490
 491        :param ax: The matplotlib axes object to set x- and y- ticks / labels too.
 492        :param interval: The interval (in m) between depth ticks. Default is 5 m.
 493        :param depth_ticks:  True (default) if depth ticks should be plotted.
 494        :param group_ticks: True (default) if group ticks should be plotted.
 495        :param rot: If True, the x- and y- axes are flipped (e.g. if image was rotated relative to this template before plotting).
 496        :param xx: subsampling in the x-direction (useful for large templates!). Default is 1 (no subsampling).
 497        :param yy: subsampling in the y-direction (useful for large templates!). Default is 1 (no subsampling).
 498        :param angle: rotation used for the x-ticks. Default is 45 degrees.
 499        """
 500        a = self.depth_axis
 501        if rot:
 502            a = int(1 - a)
 503            _xx = xx
 504            xx = yy
 505            yy = _xx
 506
 507        # get depth and group ticks
 508        if depth_ticks:
 509            zt, zz = self.get_depth_ticks( interval )
 510        if group_ticks:
 511            gt,gg = self.get_group_ticks()
 512
 513        if a == 0:
 514            if depth_ticks:
 515                ax.set_xticks(zt / xx )
 516                ax.set_xticklabels( ["%.1f" % z for z in zz], rotation=angle )
 517                #ax.tick_params('x', labelrotation=angle )
 518            if group_ticks and self.group_ticks is not None:
 519                ax.set_yticks(gt / yy )
 520                ax.set_yticklabels( ["%s" % g for g in gg] )
 521        else:
 522            if depth_ticks:
 523                ax.set_yticks(zt / xx )
 524                ax.set_yticklabels(["%.1f" % z for z in zz])
 525            if group_ticks:
 526                ax.set_xticks(gt / yy)
 527                ax.set_xticklabels(["%s" % g for g in gg], rotation=angle)
 528                #ax.tick_params('x', labelrotation=angle)
 529
 530    def get_group_ticks(self):
 531        """
 532        :return: The position and label of group ticks defined in this template, or [], [] if None are defined.
 533        """
 534        if (self.groups is not None) and (self.group_ticks is not None):
 535            return self.group_ticks, self.groups
 536        else:
 537            return np.array([]), np.array([])
 538
 539    def get_depth_ticks(self, interval=1.0):
 540        """
 541        Get evenly spaced depth ticks for pretty plotting.
 542        :param interval: The desired spacing between depth ticks
 543        :return: Depth tick positions and values. If depth_ticks and depths are not defined, this will return empty lists.
 544        """
 545        if (self.from_depth is None) or (self.to_depth is None) or (self.depth_ticks is None) or (self.depths is None):
 546            return np.array([]), np.array([])
 547        else:
 548            zz = np.arange(self.from_depth - self.from_depth % interval,
 549                           self.to_depth + interval - self.to_depth % interval, interval )[1:]
 550
 551            tt = np.interp( zz, self.depths, self.depth_ticks)
 552
 553            return tt, zz
 554
 555    def add_outlines(self, image, color=0.4, mode='thick', xx: int = 1, yy: int = 1):
 556        """
 557        Add outlines from this template to the specified image.
 558
 559        :param image: a HyImage instance to add colours too. Note that this will be updated in-place.
 560        :param color: a float or tuple containing the values of the colour to apply.
 561        :param mode: outline mode. Options are ‘thick’, ‘inner’, ‘outer’, ‘subpixel’ (see skimage.segmentation.mark_boundaries for details).
 562        """
 563        dtype = image.data.dtype  # store this for later
 564
 565        # get mask to outline
 566        mask = self.index[::xx, ::yy, 1] != -1
 567
 568        # sort out colour
 569        if isinstance(color, float) or isinstance(color, int):
 570            color = tuple([color for i in range(image.band_count())])
 571        assert len(color) == image.band_count(), "Error - colour must have same number of bands as image. %d != %d" % (
 572        len(color), image.band_count())
 573        if (np.array(color) > 1).any():
 574            color = np.array(color) / 255.
 575
 576        # mark boundaries using scikit-image
 577        from skimage.segmentation import mark_boundaries
 578        image.data = mark_boundaries(image.data, mask, color=color, mode=mode)
 579
 580        if (dtype == np.uint8):
 581            image.data = (image.data * 255)  # scikit image transforms our data to 0 - 1 range...
 582
 583    def toImage(self):
 584        """
 585        Convert this Template object to a HyImage instance with the relevant additional hole and box lists stored
 586        in the header file. This can be saved and then later converted back to a Template using fromImage( ... ).
 587        :return: A HyImage representation of this template.
 588        """
 589        image = hylite.HyImage(self.index)
 590        image.header['root'] = self.root
 591        image.header['boxes'] = self.boxes
 592        if self.from_depth is not None:
 593            image.header['from_depth'] = self.from_depth
 594        if self.to_depth is not None:
 595            image.header['to_depth'] = self.to_depth
 596        if self.center_depth is not None:
 597            image.header['center_depth'] = self.center_depth
 598        if self.groups is not None:
 599            image.header['groups'] = self.groups
 600        if self.group_ticks is not None:
 601            image.header['group_ticks'] = self.group_ticks
 602        if self.depths is not None:
 603            image.header['depths'] = self.depths
 604        if self.depth_ticks is not None:
 605            image.header['depth_ticks'] = self.depth_ticks
 606        if self.depth_axis is not None:
 607            image.header['depth_axis'] = self.depth_axis
 608
 609        return image
 610
 611    @classmethod
 612    def fromImage(cls, image):
 613        """
 614        Convert a HyImage with the relevant header information to a Template instance. Useful for IO.
 615        :param image: The HyImage instance containing the template mapping and relevant header metadata
 616                        (lists of hole and box names).
 617        :return:
 618        """
 619        assert 'root' in image.header, 'Error - image must have a "root" key in its header'
 620        assert 'boxes' in image.header, 'Error - image must have a "boxes" key in its header'
 621        assert image.band_count() == 3, 'Error - image must have four bands [holeID, boxID, xidx, yidx]'
 622        root = image.header['root']
 623        boxes = image.header.get_list('boxes')
 624        from_depth = None
 625        to_depth = None
 626        groups = None
 627        group_ticks = None
 628        depths = None
 629        depth_ticks = None
 630        depth_axis = None
 631        if 'from_depth' in image.header:
 632            from_depth = float(image.header['from_depth'])
 633        if 'to_depth' in image.header:
 634            to_depth = float(image.header['to_depth'])
 635        if 'groups' in image.header:
 636            groups = image.header.get_list('groups')
 637        if 'group_ticks' in image.header:
 638            group_ticks = image.header.get_list('group_ticks')
 639        if 'depths' in image.header:
 640            depths = image.header.get_list('depths')
 641        if 'depth_ticks' in image.header:
 642            depth_ticks = image.header.get_list('depth_ticks')
 643        if 'depth_axis' in image.header:
 644            depth_axis = int(image.header['depth_axis'])
 645        return Template([os.path.join( root, b) for b in boxes], image.data, from_depth=from_depth, to_depth=to_depth,
 646                        groups=groups, group_ticks=group_ticks, depths=depths, depth_ticks=depth_ticks, depth_axis=depth_axis)
 647
 648    def rot90(self):
 649        """
 650        Rotate this template by 90 degrees.
 651        """
 652        self.index = np.rot90(self.index, axes=(0, 1))
 653        self.depth_axis = int(1 - self.depth_axis)
 654
 655    def crop(self, min_depth : float, max_depth : float, axis : int , offset : float = 0):
 656        """
 657        Crop this template to the specified depth range.
 658
 659        :param min_depth: The minimum allowable depth.
 660        :param max_depth: The maximum allowable depth.
 661        :param axis: The axis along which depth is interpolated in this template. Should be 0 (x-axis is depth axis) or 1 (y-axis is depth axis).
 662        :param offset: A depth to subtract from min_depth and max_depth prior to cropping.
 663        :return: A copy of this template, cropped to the specific range, or None if no overlap exists.
 664        """
 665        # check there is overlap
 666        if (self.from_depth is None) or (self.to_depth is None):
 667            assert False, "Error - template has no depth information."
 668
 669        # interpolate depth
 670        zz = np.linspace( self.from_depth, self.to_depth, self.index.shape[axis] ) - offset
 671        mask = (zz >= min_depth) & (zz <= max_depth)
 672        if not mask.any():
 673            return None # no overlap
 674
 675        if axis == 0:
 676            ix = self.index[mask, :, : ]
 677        else:
 678            ix = self.index[:, mask, : ]
 679
 680        # print( min_depth, max_depth, self.from_depth, self.to_depth, np.min(zz[mask]), np.max(zz[mask]) )
 681        return Template( [os.path.join(self.root, b) for b in self.boxes], ix,
 682                         from_depth = np.min(zz[mask]),
 683                         to_depth = np.max(zz[mask]) ) # return cropped template
 684
 685    @classmethod
 686    def stack(cls, templates: list, xstep : int = 1, ystep : int = 1, axis=1):
 687        """
 688        Stack a list of templates along the specified axis (similar to np.vstack and np.hstack).
 689
 690        :param templates: A list of template objects to stack.
 691        :param xstep: Step to use in the x-direction. Useful for skipping pixels in the source image when generating large mosaics.
 692        :param ystep: Step to use in the y-direction. Useful for skipping pixels in the source image when generating large mosaics.
 693        :param axis: The axis to stack along. Set as zero to stack in the x-direction and 1 to stack in the
 694                     y-direction.
 695        """
 696
 697        # resolve all unique paths
 698        paths = set()
 699        for t in templates:
 700            for b in t.boxes:
 701                paths.add(os.path.join(t.root, b))
 702                assert os.path.exists(os.path.join(t.root, b)), "Error - one or more template directories do not exist?"
 703
 704        # get root (lowest common base) and express boxes as relative paths to this
 705        paths = list(paths)
 706
 707        # initialise output
 708        if axis == 0:
 709            out = np.full((sum([t.index[::xstep, ::ystep, :].shape[0] for t in templates]),
 710                            max([t.index[::xstep, ::ystep, :].shape[1] for t in templates]), 3), -1)
 711        else:
 712            out = np.full((max([t.index[::xstep, ::ystep, :].shape[0] for t in templates]),
 713                            sum([t.index[::xstep, ::ystep, :].shape[1] for t in templates]), 3), -1)
 714
 715        # loop through templates and stack
 716        p = 0
 717        groups = []
 718        group_ticks = []
 719        for i, t in enumerate(templates):
 720            # copy block of indices across
 721            if axis == 0:
 722                out[p:(p + t.index[::xstep, ::ystep, :].shape[0]),
 723                        0:t.index[::xstep, ::ystep, :].shape[1], :] = t.index[::xstep, ::ystep, :]
 724            else:
 725                out[0:t.index[::xstep, ::ystep, :].shape[0],
 726                p:(p + t.index[::xstep, ::ystep, :].shape[1]), :] = t.index[::xstep, ::ystep, :]
 727
 728            # update box indices
 729            for j, b in enumerate(t.boxes):
 730                mask = np.full((out.shape[0], out.shape[1]), False)
 731                if axis == 0:
 732                    mask[p:(p + t.index[::xstep, ::ystep, :].shape[0]), 0:t.index[::xstep, ::ystep, :].shape[1]] = (t.index[::xstep, ::ystep, 0] == j)
 733                else:
 734                    mask[0:t.index[::xstep, ::ystep, :].shape[0], p:(p + t.index[::xstep, ::ystep, :].shape[1])] = (t.index[::xstep, ::ystep, 0] == j)
 735                out[mask, 0] = paths.index(os.path.join(t.root, b))
 736
 737            # update groups and group ticks (these are useful for subsequent plotting)
 738
 739            if t.groups is not None:
 740                groups += list(t.groups)
 741                if axis == 0:
 742                    group_ticks += list( np.array(t.group_ticks) / xstep + p )
 743                else:
 744                    group_ticks += list(np.array(t.group_ticks) / ystep + p)
 745
 746            # update start point
 747            p += t.index[::xstep, ::ystep, :].shape[axis]
 748
 749        # get span of depths
 750        from_depth = None
 751        to_depth = None
 752        if np.array([t.center_depth is not None for t in templates]).all():
 753            from_depth = np.min([t.from_depth for t in templates])
 754            to_depth = np.max([t.to_depth for t in templates])
 755
 756        # generate depth ticks
 757        # i = 1 - axis # if axis is 1, we tick along axis = 0, if axis is 0, we tick along axis = 1
 758        ticks = [templates[0].index.shape[axis] / 2]
 759        depths = [templates[0].from_depth]
 760        for i, T in enumerate(templates[1:]):
 761            ticks.append(ticks[-1] + templates[i - 1].index.shape[axis] / 2 + T.index.shape[axis] / 2)
 762            depths.append(T.from_depth)
 763
 764        # return new Template instance
 765        return Template(paths, out, from_depth = from_depth, to_depth = to_depth,
 766                        groups=groups, group_ticks=group_ticks,
 767                        depths=depths, depth_ticks=ticks, depth_axis=axis)
 768
 769    def getDepths(self, res: float = 1e-3):
 770        """
 771        Return a 1D array of the depths corresponding to each pixel. Assumes a linear mapping
 772        between the templates from_depth and to_depth.
 773        :param res: The known resolution of the image data. If None, depths are simply stretched evenly between
 774                    the start and end of this template. If specified, the start_depth is used as an
 775                    anchor and the depth of pixels below this computed to match the resolution. This is important
 776                    to preserve true scale when core boxes contain gaps.
 777        :return: A 1D array containing depth information for each pixel in this template.
 778        """
 779        axis = self.depth_axis
 780        if res is None:
 781            return np.linspace(self.from_depth, self.to_depth, self.index.shape[axis])
 782        else:
 783            to_depth = self.from_depth + self.index.shape[axis] * res
 784            return np.linspace(self.from_depth, to_depth, self.index.shape[axis])
 785
 786    def getGrid(self, grid=50, minor=True, labels=True, background=True, res : float = 1e-3):
 787        """
 788        Create a depth grid image to accompany HSI mosaics.
 789
 790        :param grid: The grid step, in mm. Default is 50.
 791        :param minor: True if minor ticks (with half the spacing of the major ticks) should be plotted.
 792        :param labels: True if label text describing the meterage should be added.
 793        :param background: True if background outlines of the core blocks should be added.
 794        :param res: The known resolution of the image data. If None, depths are simply stretched evenly between
 795                    the start and end of this template. If specified, the start_depth is used as an
 796                    anchor and the depth of pixels below this computed to match the resolution. This is important
 797                    to preserve true scale when core boxes contain gaps.
 798        :return: A HyImage instance containing the grid image.
 799        """
 800        # import this here in case of problematic cv2 install
 801        import cv2
 802
 803        # get background image showing core blocks
 804        img = np.zeros((self.index.shape[0], self.index.shape[1], 3), dtype=np.uint8)
 805        if background:
 806            img[:, :, 1] = img[:, :, 2] = 120 * (self.index[:, :, 2] > 1)
 807
 808        # interpolate depth
 809        zz = self.getDepths(res=res)
 810
 811        # add ticks
 812        ignore = set()
 813        for i, z in enumerate(zz):
 814            zi = int(z * 1000)
 815
 816            # major ticks
 817            if zi not in ignore:
 818                if (zi % int(grid)) == 0:
 819                    # add tick
 820                    img[i, :, :] = 255
 821                    ignore.add(zi)
 822
 823                    # add depth label
 824                    if labels:
 825                        l = "%.2f" % z
 826                        font = cv2.FONT_HERSHEY_SIMPLEX
 827                        img = cv2.putText(img,
 828                                          l, (0, i - 3), font, 0.5, (255, 255, 255), 1, bottomLeftOrigin=False)
 829            # minor ticks
 830            if (zi not in ignore) and minor:
 831                if (int(z * 1000) % int(grid / 2)) == 0:
 832                    img[i, ::3, :] = 255
 833                    ignore.add(zi)
 834
 835        return hylite.HyImage(img)
 836
 837    def __lt__(self, other):
 838        """
 839        Do comparisons based on depth of centerpoint. Used for quickly sorting templates by depth.
 840        """
 841        if self.center_depth is None:
 842            assert False, 'Error - please define depth data for Template to use < functions.'
 843        if isinstance(other, Template):
 844            if other.center_depth is None:
 845                assert False, 'Error - please define depth data for Template to use < functions.'
 846            return self.center_depth < other.center_depth
 847        else:
 848            return other > self.center_depth # use operator from other class
 849
 850    def __gt__(self, other):
 851        """
 852        Do comparisons based on depth of centerpoint. Used for quickly sorting templates by depth.
 853        """
 854        if self.center_depth is None:
 855            assert False, 'Error - please define depth data for Template to use > functions.'
 856        if isinstance(other, Template):
 857            if other.center_depth is None:
 858                assert False, 'Error - please define depth data for Template to use < functions.'
 859            return self.center_depth > other.center_depth
 860        else:
 861            return other < self.center_depth # use operator from other class
 862
 863
 864class Canvas(MutableMapping):
 865    """
 866    A utility class for creating collections of templates and combining them into potentially complex layouts. This
 867    stores groups of templates, which can then be sorted and arranged in various ways (e.g., arranging groups as
 868    columns and cropping to a specific depth range, with individual drillhole offsets).
 869    """
 870
 871    def __init__(self, *args, **kwargs):
 872        self.store = dict()
 873        self.update(dict(*args, **kwargs))  # use the free update to set keys
 874
 875
 876    def hpole(self, from_depth: float = None, to_depth: float = None, scaled=False, groups: list = None,
 877                    res: float = 1e-3, depth_offsets: dict = {}, pad: int = 5 ):
 878        """
 879        Construct a "horizontal pole" type template for visualising and corellating between one or more drillholes.
 880        This has a layout as follows:
 881
 882                          -------------------------------------------------
 883        core (group) 1 - |  [xxxxxxxxxx] [xxxx]         [xxxxxxxxxxxxxxx]  |
 884        core (group) 2 - |  [xxxxx]       [xxxxxxxxxxxx]         [xxxxxx]  |
 885        core (group) 3 - |  [xxxxxxxx] [xxxxxxxxxxxxxxxxxx][xxxxxxxxxxxx]  |
 886                          -------------------------------------------------
 887
 888        :param from_depth: The top depth of the template view area, or None to include all depths.
 889        :param to_depth: The lower depth of the template view area, or None to include all depths.
 890        :param scaled: If True, a constant scale will be used on the z-axis. If False (default), cores will be stacked vertically
 891                (with small gaps representing non-contiguous intervals).
 892        :param groups: Names of the groups to plot (in order!). If None (default) then all groups are plotted.
 893        :param res: Resolution of the imagery in meters (used when deriving vertical scale). Defaults to 1e-3 (1 mm).
 894        :param depth_offsets: A dictionary containing depth values to be subtracted from sub-templates with matching
 895                                group names. Useful for e.g., plotting boreholes relative to a marker horizon rather than
 896                                in absolute terms.
 897        :param pad: Padding for template stacking. Default is 5.
 898        :return: A single combined Template class in horizontal pole layout.
 899        """
 900
 901        S, from_depth, to_depth, groups, paths = self._preprocessTemplates(depth_offsets, from_depth,
 902                                                                           groups, to_depth )
 903
 904        # compute width of output image
 905        w = pad
 906        for g in groups:
 907            w += np.max([T.index.shape[1] for T in S[g.lower()]]) + pad
 908
 909        if scaled:
 910            # compute image dimension in depth direction
 911            nz = int(np.abs(to_depth - from_depth) / res)
 912
 913            # compute corresponding depths
 914            z = np.linspace(from_depth, to_depth, nz)
 915        else:
 916            # determine maximum size of stacked boxes, including gaps, and hence template dimensions
 917            z = []
 918            for g in groups:
 919                nz = 0 # this is the dimensions of our output in pixels
 920                for i, T in enumerate(S[g.lower()]):
 921                    if (i > 0) and (abs(T.from_depth - S[g.lower()][i-1].to_depth) > 0.5):
 922                        nz += 10*pad # add in gaps for non-contiguous cores
 923                        z.append( np.linspace(S[g.lower()][i-1].to_depth, T.from_depth, 10*pad ) )
 924
 925                    nz += T.index.shape[0] + pad
 926                    z.append(np.linspace(T.from_depth, T.to_depth, T.index.shape[0]))
 927                    z.append([T.to_depth for i in range(pad)])
 928            z = np.hstack(z)
 929
 930        assert len(z) == nz, "Error - %d depths and %d pixels. Should be the same." % (len(z), nz) # debugging
 931
 932        # build index
 933        index = np.full((nz, w, 3), -1, dtype=int)
 934        tticks = []  # store tick positions in transverse direction (y-axis for hpole)
 935
 936        # stack templates
 937        _y = pad
 938        for g in groups:
 939            g = g.lower()
 940            for T in S[g]:
 941                # find depth position of center and copy data across
 942                if len(T.boxes) > 1:
 943                    assert False, "Error, cannot use multi-box templates on a Canvas (yet)"
 944                else:
 945                    six = int(np.argmin(np.abs(z - T.from_depth)))  # start index in z array
 946                    eix = min(T.index.shape[0],
 947                              (index.shape[0] - six))  # end index in template (to allow for possible overflows)
 948
 949                    # copy data!
 950                    bix = int(paths.index(os.path.join(T.root, T.boxes[0])))
 951                    index[six:(six + T.index.shape[0]), _y:(_y + T.index.shape[1]), 0] = bix  # set box index
 952
 953                    index[six:(six + eix), _y:(_y + T.index.shape[1]), 1:] = T.index[0:eix, :,
 954                                                                             1:]  # copy pixel indices
 955
 956            # step to the right
 957            h = int(np.max([T.index.shape[1] for T in S[g]]) + pad)
 958            tticks.append(int(_y + (h / 2)))
 959            _y += h
 960
 961        out = Template(paths, index, from_depth, to_depth, depth_axis=0,
 962            groups = groups, group_ticks = tticks, depths = z, depth_ticks = np.arange(len(z)))
 963
 964        # done!
 965        return out
 966
 967    def vfence(self, from_depth: float = None, to_depth: float = None, scaled=False,
 968               groups: list = None, depth_offsets : dict = {}, pad: int = 5):
 969        """
 970        Construct a "horizontal fence" type template for visualising drillholes in a condensed way.
 971        This has a layout as follows:
 972
 973            core 1       core 2         core 3
 974    1  - | ======== | | =========| | ========== |
 975         | ======== | | =========| | ========== |
 976    2  - | ======== | | ======   | | =====      |
 977         | ======== |     gap      | ========== |
 978    3  - | ======   | | =========| | ========== |
 979         | ======== | | =========| | ========== |
 980
 981        :param from_depth: The top depth of the template view area, or None to include all depths.
 982        :param to_depth: The lower depth of the template view area, or None to include all depths.
 983        :param scaled: If True, a constant scale will be used on the z-axis. If False (default), cores will be stacked vertically
 984                        (with small gaps representing non-contiguous intervals).
 985        :param groups: Names of the groups to plot (in order!). If None (default) then all groups are plotted.
 986        :param res: Resolution of the imagery in meters (used when deriving vertical scale). Defaults to 1e-3 (1 mm).
 987        :param depth_offsets: A dictionary containing depth values to be subtracted from sub-templates with matching
 988                                group names. Useful for e.g., plotting boreholes relative to a marker horizon rather than
 989                                in absolute terms.
 990        :param pad: Padding for template stacking. Default is 5.
 991        :return: A single combined Template class in horizontal pole layout.
 992        """
 993
 994        S, from_depth, to_depth, groups, paths = self._preprocessTemplates(depth_offsets, from_depth,
 995                                                                           groups, to_depth )
 996
 997        # compute width used for each group and hence image width
 998        # also compute y-scale based maximum template height to depth covered ratio
 999        w = pad # width
1000        ys = np.inf # shared y-axis pixel to depth scale (meters per pixel)
1001        for g in groups:
1002            w = w + np.max([T.index.shape[0] for T in S[g.lower()]]) + pad
1003            for T in S[g.lower()]:
1004                ys = min( ys, abs(T.to_depth - T.from_depth) / T.index.shape[1] )
1005
1006        # compute image dimension in depth direction
1007        if scaled:
1008            # determine depth-scale along y-axis (distance down hole per pixel)
1009            nz = int(np.abs(to_depth - from_depth) / ys)
1010            z = np.linspace(from_depth, to_depth, nz ) # depth per pixel array (kinda...)
1011
1012            # build index
1013            index = np.full((w, nz + pad, 3), -1, dtype=int)
1014
1015        else:
1016            # determine maximum height of stacked boxes, including gaps, and hence template dimensions
1017            heights = []
1018            for g in groups:
1019                h = 0
1020                for i, T in enumerate(S[g.lower()]):
1021                    h += T.index.shape[1] + pad
1022                    if (i > 0) and (abs(T.from_depth - S[g.lower()][i-1].to_depth) > 0.5):
1023                        h += T.index.shape[1] # add in gaps for non-contiguous cores
1024                heights.append(h)
1025
1026            ymax = np.max( heights )
1027
1028            # build index
1029            index = np.full((w, ymax + pad, 3), -1, dtype=int)
1030
1031        tticks = []  # store group tick positions in transverse direction (x-axis)
1032
1033        # stack templates
1034        _x = pad
1035        for g in groups: # loop through groups
1036            zticks = []  # store depth ticks in the down-hole direction (y-axis)
1037            zvals = []  # store corresponding depth values
1038
1039            g = g.lower()
1040            six=0
1041            for i,T in enumerate(S[g]): # loop through templates in this group
1042                # find depth position of center and copy data across
1043                if len(T.boxes) > 1:
1044                    assert False, "Error, cannot use multi-box templates on a Canvas (yet)"
1045                else:
1046                    if scaled:
1047                        six = int(np.argmin(np.abs(z - T.from_depth)))  # start index in z array
1048                    else:
1049                        # add gaps for non-contiguous templates
1050                        if i > 0 and (abs(S[g][i - 1].to_depth - T.from_depth) > 0.5):
1051                            six += T.index.shape[1]  # add full-box sized gap
1052
1053                    # copy data!
1054                    bix = int(paths.index(os.path.join(T.root, T.boxes[0])))
1055                    index[ _x:(_x + T.index.shape[0] ) , six:(six+T.index.shape[1]), 0 ] = bix
1056                    index[ _x:(_x + T.index.shape[0] ) , six:(six+T.index.shape[1]), 1:] = T.index[:, :, 1:]  # copy pixel indices
1057
1058                    # store depth ticks
1059                    zticks.append(six)
1060                    zvals.append(T.from_depth)
1061
1062                    if not scaled:
1063                        six += T.index.shape[1]+pad # increment position
1064
1065            # step to the right
1066            w = int(np.max([T.index.shape[0] for T in S[g]]) + pad) # compute max width of core blocks in this group
1067            tticks.append(int(_x + (w / 2))) # store group ticks
1068            _x += w # step to the right
1069
1070        zticks.append(index.shape[1])
1071        zvals.append(T.to_depth) # add tick at bottom of final template / box
1072
1073        if scaled and len(groups) > 1:
1074            zvals = None
1075            depth_ticks = None # these are not defined if more than one hole is present
1076        else:
1077            # interpolate zvals to get a depth value for each pixel
1078            zvals = np.interp(np.arange(0,index.shape[1]), zticks, zvals )
1079            zticks = np.arange(index.shape[1])
1080        out = Template(paths, index, from_depth, to_depth, depth_axis=1,
1081                       groups = groups, group_ticks = tticks, depths = zvals, depth_ticks = zticks )
1082
1083        # done!
1084        return out
1085
1086
1087    def hfence(self, *args):
1088        """
1089        Construct a "horizontal fence" type template for visualising boreholes in a condensed way. This
1090        is identical to the vfence(...) layout, but rotated 90 degrees such that depth increases to the right.
1091
1092        :param args: All arguments are passed to vfence. The results are then rotated to the horizontal orientation.
1093        :return:
1094        """
1095        out = self.vfence(*args)
1096        out.rot90()
1097        return out
1098
1099    def vpole(self, *args):
1100        """
1101        Construct a "vertical pole" type template for visualising and corellating between one or more drillcores. This
1102        is identical to the hpole(...) layout, but rotated 90 degrees such that cores are vertical and depth increases
1103        downwards.
1104
1105        :param args: All arguments are passed to hpole. The results are then rotated to vertical orientation.
1106        :return:
1107        """
1108        out = self.hpole(*args)
1109        # out.index = np.transpose(out.index, (1, 0, 2)) # rotate to vertical
1110        out.rot90()
1111        return out
1112
1113    def _preprocessTemplates(self, depth_offsets, from_depth, groups, to_depth):
1114        # parse from_depth and to_depth if needed
1115        if from_depth is None:
1116            from_depth = np.min([np.min([t.from_depth for t in v]) for (k, v) in self.store.items()])
1117        if to_depth is None:
1118            to_depth = np.max([np.max([t.to_depth for t in v]) for (k, v) in self.store.items()])
1119        # ensure depth template keys are lower case!
1120        offs = {}
1121        for k, v in depth_offsets.items():
1122            offs[k.lower()] = v
1123        # crop templates to the relevant view area, and discard ones that do not fit
1124        cropped = {}
1125        for k, v in self.store.items():
1126            for T in v:
1127                assert T.from_depth is not None, "Error - depth info must be defined for template to be added."
1128                assert T.to_depth is not None, "Error - depth info must be defined for template to be added."
1129                T = T.crop(from_depth, to_depth, T.depth_axis, offs.get(k, 0))
1130                if T is not None:
1131                    # store
1132                    cropped[k.lower()] = cropped.get(k.lower(), [])
1133                    cropped[k.lower()].append(T)
1134
1135        assert len(cropped) > 0, "Error - no templates are within depth range!"
1136
1137        # sort templates by order in each group
1138        S = {}
1139        for k, v in cropped.items():
1140            S[k.lower()] = sorted(v)
1141        # resolve all unique paths
1142        paths = set()
1143        for k, v in S.items():
1144            for t in v:
1145                for b in t.boxes:
1146                    paths.add(os.path.join(t.root, b))
1147                    assert os.path.exists(
1148                        os.path.join(t.root, b)), "Error - one or more template directories do not exist?"
1149        paths = list(paths)
1150        # get group names to plot if not specified
1151        if groups is None:
1152            groups = list(S.keys())
1153        return S, from_depth, to_depth, groups, paths
1154
1155
1156    def add(self, group, template):
1157        """
1158        Add the specified template to this Canvas collection.
1159
1160        :param group: The name of the group to add this template to.
1161        :param template: The template object.
1162        """
1163        self.__setitem__(group, template)
1164
1165    def __getitem__(self, key):
1166        return self.store[self._keytransform(key)]
1167
1168    def __setitem__(self, key, value):
1169        """
1170        A shorthand way to add items to canvas.
1171        """
1172        assert isinstance(value, Template), "Error - only Templates can be added to a Canvas (for now...)"
1173        v = self.store.get(self._keytransform(key), [])
1174        v.append(value)
1175        self.store[self._keytransform(key)] = v
1176
1177    def __delitem__(self, key):
1178        del self.store[self._keytransform(key)]
1179
1180    def __iter__(self):
1181        return iter(self.store)
1182
1183    def __len__(self):
1184        return len(self.store)
1185
1186    def _keytransform(self, key):
1187        return key.lower()