parameters: (fig, name, dataview, layers=None, height=None, extents=None)
return_statement: return
docstring: Apply a cutout mask to extant layers in flatmap figure
  
      Parameters
      ----------
      fig : figure or ax
          figure to which to add cutouts
      name : str
          name of cutout shape within cutouts layer to use to crop the rest of the figure
      dataview : cortex.Volume
          cortex.Volume object being plotted (only used to get subject name)
      layers : list of layers in svg object
          layers to which the cutout will be applied. None defaults to all.
          [unclear if it's worth it to keep this input.]
      height : int
          height of resulting figure. None defaults to height specified by other
          previous compositing functions. [unclear if it's worth it to keep this
          input.]
      extents : tuple | list
          extents of figure. None defaults to previously specified extents.
          [unclear if it's worth it to keep this input.]
docstring_summary: Apply a cutout mask to extant layers in flatmap figure
docstring_tokens: Apply a cutout mask to extant layers in flatmap figure
function: def add_cutout(fig, name, dataview, layers=None, height=None, extents=None):
      """Apply a cutout mask to extant layers in flatmap figure
  
      Parameters
      ----------
      fig : figure or ax
          figure to which to add cutouts
      name : str
          name of cutout shape within cutouts layer to use to crop the rest of the figure
      dataview : cortex.Volume
          cortex.Volume object being plotted (only used to get subject name)
      layers : list of layers in svg object
          layers to which the cutout will be applied. None defaults to all.
          [unclear if it's worth it to keep this input.]
      height : int
          height of resulting figure. None defaults to height specified by other
          previous compositing functions. [unclear if it's worth it to keep this
          input.]
      extents : tuple | list
          extents of figure. None defaults to previously specified extents.
          [unclear if it's worth it to keep this input.]
      """
      if layers is None:
          layers = _get_images(fig)
      if height is None:
          height = _get_height(fig)
      if extents is None:
          extents = _get_extents(fig)
      svgobject = db.get_overlay(dataview.subject)
      # Set other cutouts to be invisible
      for co_name, co_shape in svgobject.cutouts.shapes.items():
          co_shape.visible = co_name == name
      # Get cutout image (now all white = 1, black = 0)
      svg_kws = _convert_svg_kwargs(dict(fillcolor="white", 
                                         fillalpha=1.0,
                                         linecolor="white", 
                                         linewidth=2))
      co = svgobject.get_texture('cutouts', height, labels=False, **svg_kws)[..., 0]
      if not np.any(co):
          raise Exception('No pixels in cutout region {}!'.format(name))
  
      # Bounding box indices
      LL, RR, BB, TT = np.nan, np.nan, np.nan, np.nan
      # Clip each layer to this cutout
      for layer_name, im_layer in layers.items():
          im = im_layer.get_array()
  
          # Reconcile occasional 1-pixel difference between flatmap image layers 
          # that are generated by different functions
          if not all([np.abs(aa - bb) <= 1 for aa, bb in zip(im.shape, co.shape)]):
              raise Exception("Shape mismatch btw cutout and data!")
          if any([np.abs(aa - bb) > 0 and np.abs(aa - bb) < 2 for aa, bb in zip(im.shape, co.shape)]):
              from scipy.misc import imresize
              print('Resizing! {} to {}'.format(co.shape, im.shape[:2]))
              layer_cutout = imresize(co, im.shape[:2]).astype(np.float32)/255.
          else:
              layer_cutout = copy.copy(co)
  
          # Handle different types of alpha layers. Useful for RGBVolumes if nothing else.
          if im.dtype == np.uint8:
              im = np.cast['float32'](im)/255.
              im[:,:,3] *= layer_cutout
              h, w, cdim = [float(v) for v in im.shape]
          else:
              if np.ndim(im)==3:
                  im[:,:,3] *= layer_cutout
                  h, w, cdim = [float(v) for v in im.shape]
              elif np.ndim(im)==2:
                  im[layer_cutout==0] = np.nan
                  h, w = [float(v) for v in im.shape]
          y, x = np.nonzero(layer_cutout)
          l, r, b, t = extents
          x_span = np.abs(r-l)
          y_span = np.abs(t-b)
          extents_new = [l + x.min() / w * x_span,
                         l + x.max() / w * x_span,
                         t + y.min() / h * y_span,
                         t + y.max() / h * y_span]
  
          # Bounding box indices
          iy, ix = ((y.min(), y.max()), (x.min(), x.max()))
          tmp = im[iy[0]:iy[1], ix[0]:ix[1]]
          im_layer.set_array(tmp)
          im_layer.set_extent(extents_new)
  
          # Track maxima / minima for figure
          LL = np.nanmin([extents_new[0], LL])
          RR = np.nanmax([extents_new[1], RR])
          BB = np.nanmin([extents_new[2], BB])
          TT = np.nanmax([extents_new[3], TT])
          imsize = (np.abs(np.diff(iy))[0], np.abs(np.diff(ix))[0])
  
      # Re-set figure limits
      fig, ax = _get_fig_and_ax(fig)
      ax.set_xlim(LL, RR)
      ax.set_ylim(BB, TT)
      inch_size = np.array(imsize)[::-1] / float(fig.dpi)
      fig.set_size_inches(inch_size[0], inch_size[1])
  
      return
function_tokens: def add_cutout ( fig , name , dataview , layers = None , height = None , extents = None ) : if layers is None : layers = _get_images ( fig ) if height is None : height = _get_height ( fig ) if extents is None : extents = _get_extents ( fig ) svgobject = db . get_overlay ( dataview . subject ) # Set other cutouts to be invisible for co_name , co_shape in svgobject . cutouts . shapes . items ( ) : co_shape . visible = co_name == name # Get cutout image (now all white = 1, black = 0) svg_kws = _convert_svg_kwargs ( dict ( fillcolor = "white" , fillalpha = 1.0 , linecolor = "white" , linewidth = 2 ) ) co = svgobject . get_texture ( 'cutouts' , height , labels = False , * * svg_kws ) [ ... , 0 ] if not np . any ( co ) : raise Exception ( 'No pixels in cutout region {}!' . format ( name ) ) # Bounding box indices LL , RR , BB , TT = np . nan , np . nan , np . nan , np . nan # Clip each layer to this cutout for layer_name , im_layer in layers . items ( ) : im = im_layer . get_array ( ) # Reconcile occasional 1-pixel difference between flatmap image layers  # that are generated by different functions if not all ( [ np . abs ( aa - bb ) <= 1 for aa , bb in zip ( im . shape , co . shape ) ] ) : raise Exception ( "Shape mismatch btw cutout and data!" ) if any ( [ np . abs ( aa - bb ) > 0 and np . abs ( aa - bb ) < 2 for aa , bb in zip ( im . shape , co . shape ) ] ) : from scipy . misc import imresize print ( 'Resizing! {} to {}' . format ( co . shape , im . shape [ : 2 ] ) ) layer_cutout = imresize ( co , im . shape [ : 2 ] ) . astype ( np . float32 ) / 255. else : layer_cutout = copy . copy ( co ) # Handle different types of alpha layers. Useful for RGBVolumes if nothing else. if im . dtype == np . uint8 : im = np . cast [ 'float32' ] ( im ) / 255. im [ : , : , 3 ] *= layer_cutout h , w , cdim = [ float ( v ) for v in im . shape ] else : if np . ndim ( im ) == 3 : im [ : , : , 3 ] *= layer_cutout h , w , cdim = [ float ( v ) for v in im . shape ] elif np . ndim ( im ) == 2 : im [ layer_cutout == 0 ] = np . nan h , w = [ float ( v ) for v in im . shape ] y , x = np . nonzero ( layer_cutout ) l , r , b , t = extents x_span = np . abs ( r - l ) y_span = np . abs ( t - b ) extents_new = [ l + x . min ( ) / w * x_span , l + x . max ( ) / w * x_span , t + y . min ( ) / h * y_span , t + y . max ( ) / h * y_span ] # Bounding box indices iy , ix = ( ( y . min ( ) , y . max ( ) ) , ( x . min ( ) , x . max ( ) ) ) tmp = im [ iy [ 0 ] : iy [ 1 ] , ix [ 0 ] : ix [ 1 ] ] im_layer . set_array ( tmp ) im_layer . set_extent ( extents_new ) # Track maxima / minima for figure LL = np . nanmin ( [ extents_new [ 0 ] , LL ] ) RR = np . nanmax ( [ extents_new [ 1 ] , RR ] ) BB = np . nanmin ( [ extents_new [ 2 ] , BB ] ) TT = np . nanmax ( [ extents_new [ 3 ] , TT ] ) imsize = ( np . abs ( np . diff ( iy ) ) [ 0 ] , np . abs ( np . diff ( ix ) ) [ 0 ] ) # Re-set figure limits fig , ax = _get_fig_and_ax ( fig ) ax . set_xlim ( LL , RR ) ax . set_ylim ( BB , TT ) inch_size = np . array ( imsize ) [ : : - 1 ] / float ( fig . dpi ) fig . set_size_inches ( inch_size [ 0 ] , inch_size [ 1 ] ) return