:py:mod:`odpy.ranges`
=====================

.. py:module:: odpy.ranges

.. autoapi-nested-parse::

   Copyright (C) dGB Beheer B.V.; (LICENSE) http://opendtect.org/OpendTect_license.txt
     * AUTHOR : A. Huck
     * DATE   : Nov 2018

   Module Summary
   ###############

   Tools for ranges operations

   KEY methods
   -------------

   * get_range()
     
     * gets range for sample object (start, stop, step)

   * arrayFromRange()
     
     * gets range definitions as array



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   odpy.ranges.get_range
   odpy.ranges.arrayFromRange
   odpy.ranges.get_range_steps
   odpy.ranges.getLineObj
   odpy.ranges.getTraceObj
   odpy.ranges.getZObj
   odpy.ranges.getAxesAsRanges
   odpy.ranges.getAxesAsArrays
   odpy.ranges.getIntervalStr
   odpy.ranges.printSampling
   odpy.ranges.niceNumber
   odpy.ranges.niceRange



.. py:function:: get_range(samp)

   Creates range object from input

   Parameters:
     * samp (list, array, tuple): array object with three elements [start, stop, step]

   Returns:
     * range: (start, stop, step) object

   Notes:
     * stop position is increased by addition with the step to allow for 
       complete iteration over the range




.. py:function:: arrayFromRange(rg)

   Creates array from range object

   Parameters:
     * rg (obj): range object e.g. range(0, 10, 2)

   Returns:
     * numpy array: of elements defined by range



.. py:function:: get_range_steps(samp)

   Gets range steps

   Parameters:
     * samp (list, array, tuple): array object with three elements [start, stop, step]

   Returns:
     * array: stop and start of input


.. py:function:: getLineObj(obj)

   Gets inline range from object (2D seismic line or 3D cube)

   Parameters:
     * obj (dict): with crossline, inline, Z keys
     
   Returns:
     * array: inline range[start, stop, step]

   Example:

   >>> import odpy.ranges as ranges
   >>> tkzs = {
               'Inline': [200,400,1],
               'Crossline': [500,900,2],
               'Z': [0,2000,4]
             }
             
   >>> ranges.getLineObj(tkzs)
       [200, 400, 1]



.. py:function:: getTraceObj(obj)

   Gets trace range from object (2D seismic trace or 3D cube)

   Parameters:
     * obj (dict): with crossline, inline, Z keys
     
   Returns:
     * array: crossline or trace range[start, stop, step]



.. py:function:: getZObj(obj)

   Gets depth range from object (2D seismic trace or 3D cube)

   Parameters:
     * obj (dict): with crossline, inline, Z keys
     
   Returns:
     * array: depth or Z range[start, stop, step]



.. py:function:: getAxesAsRanges(tkzs)

   Gets ranges of seismic dataset axes

   Parameters:
     * tkzs (dict): with crossline, inline, Z keys

   Returns:
     * dict: axes ranges as range object

   Example:

   >>> import odpy.ranges as ranges
   >>>  tkzs = {
                'Inline': [200,400,1],
                 'Crossline': [500,900,2],
                'Z': [0,2000,4]
               } 

   >>> ranges.getAxesAsRanges(tkzs)
       OrderedDict([('lines', range(200, 401)),
              ('traces', range(500, 902, 2)),
              ('zsamp', range(0, 2004, 4))])



.. py:function:: getAxesAsArrays(tkzs)

   Gets aarray values of seismic dataset axes ranges

   Parameters:
     * tkzs (dict): with crossline, inline, Z keys

   Returns:
     * dict: axes ranges as arrays



.. py:function:: getIntervalStr(rg, label)

   Converts and stores range along string as string

   Parameters:
     * rg (list, array, tuple): array object with three elements [start, stop, step]
     * label (str): label to be concatenated with range info

   Returns:
     * str: concatenated label and range info



.. py:function:: printSampling(tkzs)

   Prints seismic dataset axes
     


.. py:function:: niceNumber(value, round=True)

   Return a nicely rounded number.

   Parameters:
     * value : (float) Input value.
     * round : (boolean, optional). If true returned number will be rounded otherwise returns the ceiling. The default is True.

   Returns:
     * float: The nice number



.. py:function:: niceRange(min, max, maxsteps=10)

   Return a nicely rounded range - good for axes.

   Parameters:
       * min (float): range minimum
       * max (float): range maximum
       * maxsteps (int, optional): maximum number of major tick steps desired in output range. Default is 10.

   Returns:
     * tuple(niceMin: float, niceMax: float)
        * niceMin: the nicely rounded minimum
        * niceMax: the nicely rounded maximum