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        data = None
 400        for i, box in enumerate(self.boxes):
 401
 402            # get this box
 403            path = os.path.join( self.root, box )
 404            if strict:
 405                assert os.path.exists(path), "Error - could not load data from %d"
 406
 407            # load the required data
 408            try:
 409                try:
 410                    if '.' in imageName:
 411                        data = io.load(os.path.join(path, imageName) ) # extension is provided
 412                    else:
 413                        data = io.load(path).get(imageName) # look in box directory
 414                except (AttributeError, AssertionError) as e:
 415                    try:
 416                        if '.' in imageName:
 417                            data = io.load(os.path.join(path, 'results.hyc/%s'%imageName))  # extension is provided
 418                        else:
 419                            data = io.load(path).results.get(imageName) # look in results directory
 420                    except:
 421                        if strict:
 422                            assert False, "Error - could not find data %s in directory %s" % (imageName, path)
 423                        else:
 424                            continue
 425
 426                data.decompress()
 427            except (AttributeError, AssertionError) as e:
 428                if strict:
 429                    assert False, "Error - could not find data %s in directory %s" % (imageName, path )
 430                else:
 431                    continue
 432
 433            # get index and subsample as needed
 434            index = self.index[::xstep, ::ystep]
 435            if scale != 1:
 436                index = (index * scale).astype(int) # scale coordinates
 437                index[...,0] = self.index[::xstep, ::ystep, 0] # don't scale box IDs
 438
 439            # create output array
 440            if bands is not None:
 441                data = data.export_bands(bands)
 442            if out is None:
 443                # initialise output array now we know how many bands we're dealing with
 444                out = np.zeros( (index.shape[0], index.shape[1], data.band_count() ), dtype=data.data.dtype )
 445
 446            # copy data as defined in index array
 447            mask = (index[..., 0] == i) & (index[..., -1] != -1 )
 448            if mask.any():
 449                out[ mask, : ] = data.data[ index[mask, 1], index[mask, 2], : ]
 450        if len( data.get_wavelengths() ) != data.band_count():
 451            data.set_wavelengths(np.arange(data.band_count()))
 452        
 453        if data is None:
 454            assert False, "Error - could not find any data for %s" % (imageName)
 455        
 456        # return a hyimage
 457        out = hylite.HyImage( out, wav=data.get_wavelengths() )
 458        if data.has_band_names():
 459            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!
 460                out.set_band_names(data.get_band_names())
 461
 462        if (self.groups is not None) and (len(self.groups) > 0):
 463            out.header['groups'] = self.groups
 464        if (self.group_ticks is not None) and (len(self.group_ticks) > 0):
 465            out.header['group ticks'] = self.group_ticks
 466
 467        if outline is not None:
 468            self.add_outlines(out, color=outline, xx = xstep, yy = ystep )
 469        return out
 470
 471    def quick_plot(self, band=0, rot=False, xx=1, yy=1, interval=5, **kwds):
 472        """
 473        Quickly plot this template for QAQC.
 474        :param band: The band(s) to plot. Default is 0 (plot only box ID).
 475        :param rot: True if the template should be rotated 90 degrees before plotting.
 476        :param xx: subsampling in the x-direction (useful for large templates!). Default is 1 (no subsampling).
 477        :param yy: subsampling in the y-direction (useful for large templates!). Default is 1 (no subsampling).
 478        :param interval: Interval between depth ticks to add to plot.
 479        :keywords: Keywords are passed to hylite.HyImage.quick_plot( ... ).
 480        :return: fig,ax from the matplotlib figure created.
 481        """
 482        img = self.toImage()
 483        img.data = img.data[ ::xx, ::yy, : ]
 484        if rot:
 485            img.rot90()
 486        fig, ax = img.quick_plot(band, tscale=True, **kwds )
 487        self.add_ticks(ax, rot=rot, xx=xx, yy=yy, interval=interval)
 488        return fig, ax
 489
 490    def add_ticks(self, ax, interval=5, *, depth_ticks: bool = True, group_ticks: bool = True, rot: bool = False,
 491                  xx: int = 1, yy: int = 1, angle: float = 45):
 492        """
 493        Add depth and or group ticks (as stored in this template) to a matplotlib plot.
 494
 495        :param ax: The matplotlib axes object to set x- and y- ticks / labels too.
 496        :param interval: The interval (in m) between depth ticks. Default is 5 m.
 497        :param depth_ticks:  True (default) if depth ticks should be plotted.
 498        :param group_ticks: True (default) if group ticks should be plotted.
 499        :param rot: If True, the x- and y- axes are flipped (e.g. if image was rotated relative to this template before plotting).
 500        :param xx: subsampling in the x-direction (useful for large templates!). Default is 1 (no subsampling).
 501        :param yy: subsampling in the y-direction (useful for large templates!). Default is 1 (no subsampling).
 502        :param angle: rotation used for the x-ticks. Default is 45 degrees.
 503        """
 504        a = self.depth_axis
 505        if rot:
 506            a = int(1 - a)
 507            _xx = xx
 508            xx = yy
 509            yy = _xx
 510
 511        # get depth and group ticks
 512        if depth_ticks:
 513            zt, zz = self.get_depth_ticks( interval )
 514        if group_ticks:
 515            gt,gg = self.get_group_ticks()
 516
 517        if a == 0:
 518            if depth_ticks:
 519                ax.set_xticks(zt / xx )
 520                ax.set_xticklabels( ["%.1f" % z for z in zz], rotation=angle )
 521                #ax.tick_params('x', labelrotation=angle )
 522            if group_ticks and self.group_ticks is not None:
 523                ax.set_yticks(gt / yy )
 524                ax.set_yticklabels( ["%s" % g for g in gg] )
 525        else:
 526            if depth_ticks:
 527                ax.set_yticks(zt / xx )
 528                ax.set_yticklabels(["%.1f" % z for z in zz])
 529            if group_ticks:
 530                ax.set_xticks(gt / yy)
 531                ax.set_xticklabels(["%s" % g for g in gg], rotation=angle)
 532                #ax.tick_params('x', labelrotation=angle)
 533
 534    def get_group_ticks(self):
 535        """
 536        :return: The position and label of group ticks defined in this template, or [], [] if None are defined.
 537        """
 538        if (self.groups is not None) and (self.group_ticks is not None):
 539            return self.group_ticks, self.groups
 540        else:
 541            return np.array([]), np.array([])
 542
 543    def get_depth_ticks(self, interval=1.0):
 544        """
 545        Get evenly spaced depth ticks for pretty plotting.
 546        :param interval: The desired spacing between depth ticks
 547        :return: Depth tick positions and values. If depth_ticks and depths are not defined, this will return empty lists.
 548        """
 549        if (self.from_depth is None) or (self.to_depth is None) or (self.depth_ticks is None) or (self.depths is None):
 550            return np.array([]), np.array([])
 551        else:
 552            zz = np.arange(self.from_depth - self.from_depth % interval,
 553                           self.to_depth + interval - self.to_depth % interval, interval )[1:]
 554
 555            tt = np.interp( zz, self.depths, self.depth_ticks)
 556
 557            return tt, zz
 558
 559    def add_outlines(self, image, color=0.4, mode='thick', xx: int = 1, yy: int = 1):
 560        """
 561        Add outlines from this template to the specified image.
 562
 563        :param image: a HyImage instance to add colours too. Note that this will be updated in-place.
 564        :param color: a float or tuple containing the values of the colour to apply.
 565        :param mode: outline mode. Options are ‘thick’, ‘inner’, ‘outer’, ‘subpixel’ (see skimage.segmentation.mark_boundaries for details).
 566        """
 567        dtype = image.data.dtype  # store this for later
 568
 569        # get mask to outline
 570        mask = self.index[::xx, ::yy, 1] != -1
 571
 572        # sort out colour
 573        if isinstance(color, float) or isinstance(color, int):
 574            color = tuple([color for i in range(image.band_count())])
 575        assert len(color) == image.band_count(), "Error - colour must have same number of bands as image. %d != %d" % (
 576        len(color), image.band_count())
 577        if (np.array(color) > 1).any():
 578            color = np.array(color) / 255.
 579
 580        # mark boundaries using scikit-image
 581        from skimage.segmentation import mark_boundaries
 582        image.data = mark_boundaries(image.data, mask, color=color, mode=mode)
 583
 584        if (dtype == np.uint8):
 585            image.data = (image.data * 255)  # scikit image transforms our data to 0 - 1 range...
 586
 587    def toImage(self):
 588        """
 589        Convert this Template object to a HyImage instance with the relevant additional hole and box lists stored
 590        in the header file. This can be saved and then later converted back to a Template using fromImage( ... ).
 591        :return: A HyImage representation of this template.
 592        """
 593        image = hylite.HyImage(self.index)
 594        image.header['root'] = self.root
 595        image.header['boxes'] = self.boxes
 596        if self.from_depth is not None:
 597            image.header['from_depth'] = self.from_depth
 598        if self.to_depth is not None:
 599            image.header['to_depth'] = self.to_depth
 600        if self.center_depth is not None:
 601            image.header['center_depth'] = self.center_depth
 602        if self.groups is not None:
 603            image.header['groups'] = self.groups
 604        if self.group_ticks is not None:
 605            image.header['group_ticks'] = self.group_ticks
 606        if self.depths is not None:
 607            image.header['depths'] = self.depths
 608        if self.depth_ticks is not None:
 609            image.header['depth_ticks'] = self.depth_ticks
 610        if self.depth_axis is not None:
 611            image.header['depth_axis'] = self.depth_axis
 612
 613        return image
 614
 615    @classmethod
 616    def fromImage(cls, image):
 617        """
 618        Convert a HyImage with the relevant header information to a Template instance. Useful for IO.
 619        :param image: The HyImage instance containing the template mapping and relevant header metadata
 620                        (lists of hole and box names).
 621        :return:
 622        """
 623        assert 'root' in image.header, 'Error - image must have a "root" key in its header'
 624        assert 'boxes' in image.header, 'Error - image must have a "boxes" key in its header'
 625        assert image.band_count() == 3, 'Error - image must have four bands [holeID, boxID, xidx, yidx]'
 626        root = image.header['root']
 627        boxes = image.header.get_list('boxes')
 628        from_depth = None
 629        to_depth = None
 630        groups = None
 631        group_ticks = None
 632        depths = None
 633        depth_ticks = None
 634        depth_axis = None
 635        if 'from_depth' in image.header:
 636            from_depth = float(image.header['from_depth'])
 637        if 'to_depth' in image.header:
 638            to_depth = float(image.header['to_depth'])
 639        if 'groups' in image.header:
 640            groups = image.header.get_list('groups')
 641        if 'group_ticks' in image.header:
 642            group_ticks = image.header.get_list('group_ticks')
 643        if 'depths' in image.header:
 644            depths = image.header.get_list('depths')
 645        if 'depth_ticks' in image.header:
 646            depth_ticks = image.header.get_list('depth_ticks')
 647        if 'depth_axis' in image.header:
 648            depth_axis = int(image.header['depth_axis'])
 649        return Template([os.path.join( root, b) for b in boxes], image.data, from_depth=from_depth, to_depth=to_depth,
 650                        groups=groups, group_ticks=group_ticks, depths=depths, depth_ticks=depth_ticks, depth_axis=depth_axis)
 651
 652    def rot90(self):
 653        """
 654        Rotate this template by 90 degrees.
 655        """
 656        self.index = np.rot90(self.index, axes=(0, 1))
 657        self.depth_axis = int(1 - self.depth_axis)
 658
 659    def crop(self, min_depth : float, max_depth : float, axis : int , offset : float = 0):
 660        """
 661        Crop this template to the specified depth range.
 662
 663        :param min_depth: The minimum allowable depth.
 664        :param max_depth: The maximum allowable depth.
 665        :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).
 666        :param offset: A depth to subtract from min_depth and max_depth prior to cropping.
 667        :return: A copy of this template, cropped to the specific range, or None if no overlap exists.
 668        """
 669        # check there is overlap
 670        if (self.from_depth is None) or (self.to_depth is None):
 671            assert False, "Error - template has no depth information."
 672
 673        # interpolate depth
 674        zz = np.linspace( self.from_depth, self.to_depth, self.index.shape[axis] ) - offset
 675        mask = (zz >= min_depth) & (zz <= max_depth)
 676        if not mask.any():
 677            return None # no overlap
 678
 679        if axis == 0:
 680            ix = self.index[mask, :, : ]
 681        else:
 682            ix = self.index[:, mask, : ]
 683
 684        # print( min_depth, max_depth, self.from_depth, self.to_depth, np.min(zz[mask]), np.max(zz[mask]) )
 685        return Template( [os.path.join(self.root, b) for b in self.boxes], ix,
 686                         from_depth = np.min(zz[mask]),
 687                         to_depth = np.max(zz[mask]) ) # return cropped template
 688
 689    @classmethod
 690    def stack(cls, templates: list, xstep : int = 1, ystep : int = 1, axis=1):
 691        """
 692        Stack a list of templates along the specified axis (similar to np.vstack and np.hstack).
 693
 694        :param templates: A list of template objects to stack.
 695        :param xstep: Step to use in the x-direction. Useful for skipping pixels in the source image when generating large mosaics.
 696        :param ystep: Step to use in the y-direction. Useful for skipping pixels in the source image when generating large mosaics.
 697        :param axis: The axis to stack along. Set as zero to stack in the x-direction and 1 to stack in the
 698                     y-direction.
 699        """
 700
 701        # resolve all unique paths
 702        paths = set()
 703        for t in templates:
 704            for b in t.boxes:
 705                paths.add(os.path.join(t.root, b))
 706                assert os.path.exists(os.path.join(t.root, b)), "Error - one or more template directories do not exist?"
 707
 708        # get root (lowest common base) and express boxes as relative paths to this
 709        paths = list(paths)
 710
 711        # initialise output
 712        if axis == 0:
 713            out = np.full((sum([t.index[::xstep, ::ystep, :].shape[0] for t in templates]),
 714                            max([t.index[::xstep, ::ystep, :].shape[1] for t in templates]), 3), -1)
 715        else:
 716            out = np.full((max([t.index[::xstep, ::ystep, :].shape[0] for t in templates]),
 717                            sum([t.index[::xstep, ::ystep, :].shape[1] for t in templates]), 3), -1)
 718
 719        # loop through templates and stack
 720        p = 0
 721        groups = []
 722        group_ticks = []
 723        for i, t in enumerate(templates):
 724            # copy block of indices across
 725            if axis == 0:
 726                out[p:(p + t.index[::xstep, ::ystep, :].shape[0]),
 727                        0:t.index[::xstep, ::ystep, :].shape[1], :] = t.index[::xstep, ::ystep, :]
 728            else:
 729                out[0:t.index[::xstep, ::ystep, :].shape[0],
 730                p:(p + t.index[::xstep, ::ystep, :].shape[1]), :] = t.index[::xstep, ::ystep, :]
 731
 732            # update box indices
 733            for j, b in enumerate(t.boxes):
 734                mask = np.full((out.shape[0], out.shape[1]), False)
 735                if axis == 0:
 736                    mask[p:(p + t.index[::xstep, ::ystep, :].shape[0]), 0:t.index[::xstep, ::ystep, :].shape[1]] = (t.index[::xstep, ::ystep, 0] == j)
 737                else:
 738                    mask[0:t.index[::xstep, ::ystep, :].shape[0], p:(p + t.index[::xstep, ::ystep, :].shape[1])] = (t.index[::xstep, ::ystep, 0] == j)
 739                out[mask, 0] = paths.index(os.path.join(t.root, b))
 740
 741            # update groups and group ticks (these are useful for subsequent plotting)
 742
 743            if t.groups is not None:
 744                groups += list(t.groups)
 745                if axis == 0:
 746                    group_ticks += list( np.array(t.group_ticks) / xstep + p )
 747                else:
 748                    group_ticks += list(np.array(t.group_ticks) / ystep + p)
 749
 750            # update start point
 751            p += t.index[::xstep, ::ystep, :].shape[axis]
 752
 753        # get span of depths
 754        from_depth = None
 755        to_depth = None
 756        if np.array([t.center_depth is not None for t in templates]).all():
 757            from_depth = np.min([t.from_depth for t in templates])
 758            to_depth = np.max([t.to_depth for t in templates])
 759
 760        # generate depth ticks
 761        # i = 1 - axis # if axis is 1, we tick along axis = 0, if axis is 0, we tick along axis = 1
 762        ticks = [templates[0].index.shape[axis] / 2]
 763        depths = [templates[0].from_depth]
 764        for i, T in enumerate(templates[1:]):
 765            ticks.append(ticks[-1] + templates[i - 1].index.shape[axis] / 2 + T.index.shape[axis] / 2)
 766            depths.append(T.from_depth)
 767
 768        # return new Template instance
 769        return Template(paths, out, from_depth = from_depth, to_depth = to_depth,
 770                        groups=groups, group_ticks=group_ticks,
 771                        depths=depths, depth_ticks=ticks, depth_axis=axis)
 772
 773    def getDepths(self, res: float = 1e-3):
 774        """
 775        Return a 1D array of the depths corresponding to each pixel. Assumes a linear mapping
 776        between the templates from_depth and to_depth.
 777        :param res: The known resolution of the image data. If None, depths are simply stretched evenly between
 778                    the start and end of this template. If specified, the start_depth is used as an
 779                    anchor and the depth of pixels below this computed to match the resolution. This is important
 780                    to preserve true scale when core boxes contain gaps.
 781        :return: A 1D array containing depth information for each pixel in this template.
 782        """
 783        axis = self.depth_axis
 784        if res is None:
 785            return np.linspace(self.from_depth, self.to_depth, self.index.shape[axis])
 786        else:
 787            to_depth = self.from_depth + self.index.shape[axis] * res
 788            return np.linspace(self.from_depth, to_depth, self.index.shape[axis])
 789
 790    def getGrid(self, grid=50, minor=True, labels=True, background=True, res : float = 1e-3):
 791        """
 792        Create a depth grid image to accompany HSI mosaics.
 793
 794        :param grid: The grid step, in mm. Default is 50.
 795        :param minor: True if minor ticks (with half the spacing of the major ticks) should be plotted.
 796        :param labels: True if label text describing the meterage should be added.
 797        :param background: True if background outlines of the core blocks should be added.
 798        :param res: The known resolution of the image data. If None, depths are simply stretched evenly between
 799                    the start and end of this template. If specified, the start_depth is used as an
 800                    anchor and the depth of pixels below this computed to match the resolution. This is important
 801                    to preserve true scale when core boxes contain gaps.
 802        :return: A HyImage instance containing the grid image.
 803        """
 804        # import this here in case of problematic cv2 install
 805        import cv2
 806
 807        # get background image showing core blocks
 808        img = np.zeros((self.index.shape[0], self.index.shape[1], 3), dtype=np.uint8)
 809        if background:
 810            img[:, :, 1] = img[:, :, 2] = 120 * (self.index[:, :, 2] > 1)
 811
 812        # interpolate depth
 813        zz = self.getDepths(res=res)
 814
 815        # add ticks
 816        ignore = set()
 817        for i, z in enumerate(zz):
 818            zi = int(z * 1000)
 819
 820            # major ticks
 821            if zi not in ignore:
 822                if (zi % int(grid)) == 0:
 823                    # add tick
 824                    img[i, :, :] = 255
 825                    ignore.add(zi)
 826
 827                    # add depth label
 828                    if labels:
 829                        l = "%.2f" % z
 830                        font = cv2.FONT_HERSHEY_SIMPLEX
 831                        img = cv2.putText(img,
 832                                          l, (0, i - 3), font, 0.5, (255, 255, 255), 1, bottomLeftOrigin=False)
 833            # minor ticks
 834            if (zi not in ignore) and minor:
 835                if (int(z * 1000) % int(grid / 2)) == 0:
 836                    img[i, ::3, :] = 255
 837                    ignore.add(zi)
 838
 839        return hylite.HyImage(img)
 840
 841    def __lt__(self, other):
 842        """
 843        Do comparisons based on depth of centerpoint. Used for quickly sorting templates by depth.
 844        """
 845        if self.center_depth is None:
 846            assert False, 'Error - please define depth data for Template to use < functions.'
 847        if isinstance(other, Template):
 848            if other.center_depth is None:
 849                assert False, 'Error - please define depth data for Template to use < functions.'
 850            return self.center_depth < other.center_depth
 851        else:
 852            return other > self.center_depth # use operator from other class
 853
 854    def __gt__(self, other):
 855        """
 856        Do comparisons based on depth of centerpoint. Used for quickly sorting templates by depth.
 857        """
 858        if self.center_depth is None:
 859            assert False, 'Error - please define depth data for Template to use > functions.'
 860        if isinstance(other, Template):
 861            if other.center_depth is None:
 862                assert False, 'Error - please define depth data for Template to use < functions.'
 863            return self.center_depth > other.center_depth
 864        else:
 865            return other < self.center_depth # use operator from other class
 866
 867
 868class Canvas(MutableMapping):
 869    """
 870    A utility class for creating collections of templates and combining them into potentially complex layouts. This
 871    stores groups of templates, which can then be sorted and arranged in various ways (e.g., arranging groups as
 872    columns and cropping to a specific depth range, with individual drillhole offsets).
 873    """
 874
 875    def __init__(self, *args, **kwargs):
 876        self.store = dict()
 877        self.update(dict(*args, **kwargs))  # use the free update to set keys
 878
 879
 880    def hpole(self, from_depth: float = None, to_depth: float = None, scaled=False, groups: list = None,
 881                    res: float = 1e-3, depth_offsets: dict = {}, pad: int = 5 ):
 882        """
 883        Construct a "horizontal pole" type template for visualising and corellating between one or more drillholes.
 884        This has a layout as follows:
 885
 886                          -------------------------------------------------
 887        core (group) 1 - |  [xxxxxxxxxx] [xxxx]         [xxxxxxxxxxxxxxx]  |
 888        core (group) 2 - |  [xxxxx]       [xxxxxxxxxxxx]         [xxxxxx]  |
 889        core (group) 3 - |  [xxxxxxxx] [xxxxxxxxxxxxxxxxxx][xxxxxxxxxxxx]  |
 890                          -------------------------------------------------
 891
 892        :param from_depth: The top depth of the template view area, or None to include all depths.
 893        :param to_depth: The lower depth of the template view area, or None to include all depths.
 894        :param scaled: If True, a constant scale will be used on the z-axis. If False (default), cores will be stacked vertically
 895                (with small gaps representing non-contiguous intervals).
 896        :param groups: Names of the groups to plot (in order!). If None (default) then all groups are plotted.
 897        :param res: Resolution of the imagery in meters (used when deriving vertical scale). Defaults to 1e-3 (1 mm).
 898        :param depth_offsets: A dictionary containing depth values to be subtracted from sub-templates with matching
 899                                group names. Useful for e.g., plotting boreholes relative to a marker horizon rather than
 900                                in absolute terms.
 901        :param pad: Padding for template stacking. Default is 5.
 902        :return: A single combined Template class in horizontal pole layout.
 903        """
 904
 905        S, from_depth, to_depth, groups, paths = self._preprocessTemplates(depth_offsets, from_depth,
 906                                                                           groups, to_depth )
 907
 908        # compute width of output image
 909        w = pad
 910        for g in groups:
 911            w += np.max([T.index.shape[1] for T in S[g.lower()]]) + pad
 912
 913        if scaled:
 914            # compute image dimension in depth direction
 915            nz = int(np.abs(to_depth - from_depth) / res)
 916
 917            # compute corresponding depths
 918            z = np.linspace(from_depth, to_depth, nz)
 919        else:
 920            # determine maximum size of stacked boxes, including gaps, and hence template dimensions
 921            z = []
 922            for g in groups:
 923                nz = 0 # this is the dimensions of our output in pixels
 924                for i, T in enumerate(S[g.lower()]):
 925                    if (i > 0) and (abs(T.from_depth - S[g.lower()][i-1].to_depth) > 0.5):
 926                        nz += 10*pad # add in gaps for non-contiguous cores
 927                        z.append( np.linspace(S[g.lower()][i-1].to_depth, T.from_depth, 10*pad ) )
 928
 929                    nz += T.index.shape[0] + pad
 930                    z.append(np.linspace(T.from_depth, T.to_depth, T.index.shape[0]))
 931                    z.append([T.to_depth for i in range(pad)])
 932            z = np.hstack(z)
 933
 934        assert len(z) == nz, "Error - %d depths and %d pixels. Should be the same." % (len(z), nz) # debugging
 935
 936        # build index
 937        index = np.full((nz, w, 3), -1, dtype=int)
 938        tticks = []  # store tick positions in transverse direction (y-axis for hpole)
 939
 940        # stack templates
 941        _y = pad
 942        for g in groups:
 943            g = g.lower()
 944            for T in S[g]:
 945                # find depth position of center and copy data across
 946                if len(T.boxes) > 1:
 947                    assert False, "Error, cannot use multi-box templates on a Canvas (yet)"
 948                else:
 949                    six = int(np.argmin(np.abs(z - T.from_depth)))  # start index in z array
 950                    eix = min(T.index.shape[0],
 951                              (index.shape[0] - six))  # end index in template (to allow for possible overflows)
 952
 953                    # copy data!
 954                    bix = int(paths.index(os.path.join(T.root, T.boxes[0])))
 955                    index[six:(six + T.index.shape[0]), _y:(_y + T.index.shape[1]), 0] = bix  # set box index
 956
 957                    index[six:(six + eix), _y:(_y + T.index.shape[1]), 1:] = T.index[0:eix, :,
 958                                                                             1:]  # copy pixel indices
 959
 960            # step to the right
 961            h = int(np.max([T.index.shape[1] for T in S[g]]) + pad)
 962            tticks.append(int(_y + (h / 2)))
 963            _y += h
 964
 965        out = Template(paths, index, from_depth, to_depth, depth_axis=0,
 966            groups = groups, group_ticks = tticks, depths = z, depth_ticks = np.arange(len(z)))
 967
 968        # done!
 969        return out
 970
 971    def vfence(self, from_depth: float = None, to_depth: float = None, scaled=False,
 972               groups: list = None, depth_offsets : dict = {}, pad: int = 5):
 973        """
 974        Construct a "horizontal fence" type template for visualising drillholes in a condensed way.
 975        This has a layout as follows:
 976
 977            core 1       core 2         core 3
 978    1  - | ======== | | =========| | ========== |
 979         | ======== | | =========| | ========== |
 980    2  - | ======== | | ======   | | =====      |
 981         | ======== |     gap      | ========== |
 982    3  - | ======   | | =========| | ========== |
 983         | ======== | | =========| | ========== |
 984
 985        :param from_depth: The top depth of the template view area, or None to include all depths.
 986        :param to_depth: The lower depth of the template view area, or None to include all depths.
 987        :param scaled: If True, a constant scale will be used on the z-axis. If False (default), cores will be stacked vertically
 988                        (with small gaps representing non-contiguous intervals).
 989        :param groups: Names of the groups to plot (in order!). If None (default) then all groups are plotted.
 990        :param res: Resolution of the imagery in meters (used when deriving vertical scale). Defaults to 1e-3 (1 mm).
 991        :param depth_offsets: A dictionary containing depth values to be subtracted from sub-templates with matching
 992                                group names. Useful for e.g., plotting boreholes relative to a marker horizon rather than
 993                                in absolute terms.
 994        :param pad: Padding for template stacking. Default is 5.
 995        :return: A single combined Template class in horizontal pole layout.
 996        """
 997
 998        S, from_depth, to_depth, groups, paths = self._preprocessTemplates(depth_offsets, from_depth,
 999                                                                           groups, to_depth )
1000
1001        # compute width used for each group and hence image width
1002        # also compute y-scale based maximum template height to depth covered ratio
1003        w = pad # width
1004        ys = np.inf # shared y-axis pixel to depth scale (meters per pixel)
1005        for g in groups:
1006            w = w + np.max([T.index.shape[0] for T in S[g.lower()]]) + pad
1007            for T in S[g.lower()]:
1008                ys = min( ys, abs(T.to_depth - T.from_depth) / T.index.shape[1] )
1009
1010        # compute image dimension in depth direction
1011        if scaled:
1012            # determine depth-scale along y-axis (distance down hole per pixel)
1013            nz = int(np.abs(to_depth - from_depth) / ys)
1014            z = np.linspace(from_depth, to_depth, nz ) # depth per pixel array (kinda...)
1015
1016            # build index
1017            index = np.full((w, nz + pad, 3), -1, dtype=int)
1018
1019        else:
1020            # determine maximum height of stacked boxes, including gaps, and hence template dimensions
1021            heights = []
1022            for g in groups:
1023                h = 0
1024                for i, T in enumerate(S[g.lower()]):
1025                    h += T.index.shape[1] + pad
1026                    if (i > 0) and (abs(T.from_depth - S[g.lower()][i-1].to_depth) > 0.5):
1027                        h += T.index.shape[1] # add in gaps for non-contiguous cores
1028                heights.append(h)
1029
1030            ymax = np.max( heights )
1031
1032            # build index
1033            index = np.full((w, ymax + pad, 3), -1, dtype=int)
1034
1035        tticks = []  # store group tick positions in transverse direction (x-axis)
1036
1037        # stack templates
1038        _x = pad
1039        for g in groups: # loop through groups
1040            zticks = []  # store depth ticks in the down-hole direction (y-axis)
1041            zvals = []  # store corresponding depth values
1042
1043            g = g.lower()
1044            six=0
1045            for i,T in enumerate(S[g]): # loop through templates in this group
1046                # find depth position of center and copy data across
1047                if len(T.boxes) > 1:
1048                    assert False, "Error, cannot use multi-box templates on a Canvas (yet)"
1049                else:
1050                    if scaled:
1051                        six = int(np.argmin(np.abs(z - T.from_depth)))  # start index in z array
1052                    else:
1053                        # add gaps for non-contiguous templates
1054                        if i > 0 and (abs(S[g][i - 1].to_depth - T.from_depth) > 0.5):
1055                            six += T.index.shape[1]  # add full-box sized gap
1056
1057                    # copy data!
1058                    bix = int(paths.index(os.path.join(T.root, T.boxes[0])))
1059                    index[ _x:(_x + T.index.shape[0] ) , six:(six+T.index.shape[1]), 0 ] = bix
1060                    index[ _x:(_x + T.index.shape[0] ) , six:(six+T.index.shape[1]), 1:] = T.index[:, :, 1:]  # copy pixel indices
1061
1062                    # store depth ticks
1063                    zticks.append(six)
1064                    zvals.append(T.from_depth)
1065
1066                    if not scaled:
1067                        six += T.index.shape[1]+pad # increment position
1068
1069            # step to the right
1070            w = int(np.max([T.index.shape[0] for T in S[g]]) + pad) # compute max width of core blocks in this group
1071            tticks.append(int(_x + (w / 2))) # store group ticks
1072            _x += w # step to the right
1073
1074        zticks.append(index.shape[1])
1075        zvals.append(T.to_depth) # add tick at bottom of final template / box
1076
1077        if scaled and len(groups) > 1:
1078            zvals = None
1079            depth_ticks = None # these are not defined if more than one hole is present
1080        else:
1081            # interpolate zvals to get a depth value for each pixel
1082            zvals = np.interp(np.arange(0,index.shape[1]), zticks, zvals )
1083            zticks = np.arange(index.shape[1])
1084        out = Template(paths, index, from_depth, to_depth, depth_axis=1,
1085                       groups = groups, group_ticks = tticks, depths = zvals, depth_ticks = zticks )
1086
1087        # done!
1088        return out
1089
1090
1091    def hfence(self, *args):
1092        """
1093        Construct a "horizontal fence" type template for visualising boreholes in a condensed way. This
1094        is identical to the vfence(...) layout, but rotated 90 degrees such that depth increases to the right.
1095
1096        :param args: All arguments are passed to vfence. The results are then rotated to the horizontal orientation.
1097        :return:
1098        """
1099        out = self.vfence(*args)
1100        out.rot90()
1101        return out
1102
1103    def vpole(self, *args):
1104        """
1105        Construct a "vertical pole" type template for visualising and corellating between one or more drillcores. This
1106        is identical to the hpole(...) layout, but rotated 90 degrees such that cores are vertical and depth increases
1107        downwards.
1108
1109        :param args: All arguments are passed to hpole. The results are then rotated to vertical orientation.
1110        :return:
1111        """
1112        out = self.hpole(*args)
1113        # out.index = np.transpose(out.index, (1, 0, 2)) # rotate to vertical
1114        out.rot90()
1115        return out
1116
1117    def _preprocessTemplates(self, depth_offsets, from_depth, groups, to_depth):
1118        # parse from_depth and to_depth if needed
1119        if from_depth is None:
1120            from_depth = np.min([np.min([t.from_depth for t in v]) for (k, v) in self.store.items()])
1121        if to_depth is None:
1122            to_depth = np.max([np.max([t.to_depth for t in v]) for (k, v) in self.store.items()])
1123        # ensure depth template keys are lower case!
1124        offs = {}
1125        for k, v in depth_offsets.items():
1126            offs[k.lower()] = v
1127        # crop templates to the relevant view area, and discard ones that do not fit
1128        cropped = {}
1129        for k, v in self.store.items():
1130            for T in v:
1131                assert T.from_depth is not None, "Error - depth info must be defined for template to be added."
1132                assert T.to_depth is not None, "Error - depth info must be defined for template to be added."
1133                T = T.crop(from_depth, to_depth, T.depth_axis, offs.get(k, 0))
1134                if T is not None:
1135                    # store
1136                    cropped[k.lower()] = cropped.get(k.lower(), [])
1137                    cropped[k.lower()].append(T)
1138
1139        assert len(cropped) > 0, "Error - no templates are within depth range!"
1140
1141        # sort templates by order in each group
1142        S = {}
1143        for k, v in cropped.items():
1144            S[k.lower()] = sorted(v)
1145        # resolve all unique paths
1146        paths = set()
1147        for k, v in S.items():
1148            for t in v:
1149                for b in t.boxes:
1150                    paths.add(os.path.join(t.root, b))
1151                    assert os.path.exists(
1152                        os.path.join(t.root, b)), "Error - one or more template directories do not exist?"
1153        paths = list(paths)
1154        # get group names to plot if not specified
1155        if groups is None:
1156            groups = list(S.keys())
1157        return S, from_depth, to_depth, groups, paths
1158
1159
1160    def add(self, group, template):
1161        """
1162        Add the specified template to this Canvas collection.
1163
1164        :param group: The name of the group to add this template to.
1165        :param template: The template object.
1166        """
1167        self.__setitem__(group, template)
1168
1169    def __getitem__(self, key):
1170        return self.store[self._keytransform(key)]
1171
1172    def __setitem__(self, key, value):
1173        """
1174        A shorthand way to add items to canvas.
1175        """
1176        assert isinstance(value, Template), "Error - only Templates can be added to a Canvas (for now...)"
1177        v = self.store.get(self._keytransform(key), [])
1178        v.append(value)
1179        self.store[self._keytransform(key)] = v
1180
1181    def __delitem__(self, key):
1182        del self.store[self._keytransform(key)]
1183
1184    def __iter__(self):
1185        return iter(self.store)
1186
1187    def __len__(self):
1188        return len(self.store)
1189
1190    def _keytransform(self, key):
1191        return key.lower()