""" General purpose classes for plotting utility.

    Many of these classes and function are helpful for laying out the
    location of element of a graph (titles, tick labels, ticks, etc).
    A simple class for handling properties of graph elements is also
    included.  Everything here is independent of any specific GUI or
    drawing platform
    .
    The classes and functions break out into 3 main sections:

    General layout:
        class box_object   -- Helps align rectangular graph elements
                              relative to one another.  Currently only
                              Int values are allowed for box dimensions.
        class point_object -- Alignment of points with one-another or
                              box_objects.
    Property Management:
        class poperty_object -- base class for any graph object that
                                manages a set of properties.  Pretty
                                low-tech compared to graphite and Zope.
                                It could use additions for error checking.

    Axis layout functions:
        auto_ticks          -- find set of tick locations for an axis.
        format_tick_labels  -- convert the numerical tick values to strings
                               for labels
        auto_interval       -- determine an appropriate tick interval for axis
        auto_bounds         -- determine appropriate end points for axis
        and a few others...
"""


#----------------------------------------------------------
#               General layout classes
#----------------------------------------------------------
from Numeric import *
from numpy.core.umath import *
import numpy.limits as limits
import numpy as misc

LEFT,RIGHT,TOP,BOTTOM = 0,1,2,3 # used by same_as() method

TYPE = Int # all values in a box_object are forced to be integers
           # might change this later when we've looked at round off
           # issues more thoroughly.

class box_object:
    """ Helpful for laying out rectangles.

        This class has three general areas of functionality:
            1. Retreive information about a box such as it's size,
               the x-coordinate of its left side, and others.
            2. Specify the location of one box (rectangle) in relation to
               another using methods such as left_of(), above(),
               or center_on().
            3. Change the size (and location) of a box by either choping off
               a portion of the box using trim_right(), trim_left(), and
               others or inflating the box by a percentage.
    """
    def __init__(self,topleft,size):
        self.topleft = asarray(topleft,TYPE)
        self._size = asarray(size,TYPE)

    #--------------- interrogation functions --------------------#
    def left(self):
        "Return the x-coordinate of the left edge."
        return self.topleft[0]
    def right(self):
        "Return the x-coordinate of the right edge."
        return self.topleft[0] + self.width()
    def top(self):
        "Return the y-coordinate of the top edge."
        return self.topleft[1]
    def bottom(self):
        "Return the y-coordinate of the bottom edge."
        return self.topleft[1] + self.height()
    def center_x(self):
        "Return the x-coordinate of the boxes center."
        return self.topleft[0] + .5 * self.width()
    def center_y(self):
        "Return the y-coordinate of the left edge."
        return self.topleft[1] + .5 * self.height()
    def size(self):
        "Return the size of the box as array((width,height))."
        return self._size
    def width(self):
        "Return the width of the box (length along x-axis)"
        return self.size()[0]
    def height(self):
        "Return the width of the box (length along y-axis)"
        return self.size()[1]
    def center(self):
        "Return the coordinates of the boxes center as an array"
        return self.topleft + .5 * self.size()
    def radial(self,angle):
        """ Length of a ray extending from the center of the box at the
            specified polar angle (in radians) to the edge of the box"""
        # Could have some div_by_zero errors if h or w = 0
        #   --> haven't thought about this much
        w,h = self.size()
        slope = abs(tan(angle))
        if slope > float(h)/w:
            s1 = h*.5
            s2 = s1/slope
        else:
            s1 = w*.5
            s2 = s1*slope
        return sqrt(s1**2+s2**2)

    #------------- Moving and resizing methods ----------------#
    def move(self,location):
        """ Move box so that its top left corner is located at
            the specified location.  Location is an (x,y) pair."""
        self.topleft = asarray(location,TYPE)
    def translate(self,offset):
        """ Shift the box's location by the amount specifed in
            offset.  Offset is an (x,y) pair."""
        self.topleft = self.topleft + asarray(offset,TYPE)
    def set_size(self,sz):
        """ Set the size of the box. sz is an (x,y) pair."""
        self._size = asarray(sz,TYPE)
    def set_width(self,width):
        """ Set the width of the box. sz is a numeric value"""
        self.set_size((width,self.height()))
    def set_height(self,height):
        """ Set the height of the box. sz is a numeric value."""
        self.set_size((self.width(),height))

    #-------------------- Relational Positioning ----------------#
    def above(self,other_box,margin=0):
        """Move box so that its bottom edge has same y-coord of the
           top edge of other_box.  The size does not change.  Optionally,
           margin specifies the gap between the boxes."""
        self.topleft[1] = other_box.top() - self.height() - margin
    def below(self,other_box,margin=0):
        """Move box so that its top edge has same y-coord of the
           bottom edge of other_box.  The size does not change.  Optionally,
           margin specifies the gap between the boxes."""
        self.topleft[1] = other_box.bottom() + margin
    def left_of(self,other_box,margin=0):
        """Move box so that its right edge has same x-coord of the
           left edge of other_box.  The size does not change.  Optionally,
           margin specifies the gap between the boxes."""
        self.topleft[0] = other_box.left() - self.width() - margin
    def right_of(self,other_box,margin=0):
        """Move box so that its left edge has same x-coord of the
           right edge of other_box.  The size does not change.  Optionally,
           margin specifies the gap between the boxes."""
        self.topleft[0] = other_box.right() + margin
    def center_on_x_of(self,other_box):
        """Move box so that x-coord of its center equals the x-coord of
           other_box's center. The size does not change."""
        self.topleft[0] = other_box.center_x() - .5 * self.width()
    def center_on_y_of(self,other_box):
        """Move box so that y-coord of its center equals the y-coord of
           other_box's center. The size does not change."""
        self.topleft[1] = other_box.center_y() - .5 * self.height()
    def center_on(self,other_box):
        """Move box so that its center is the same as other_box's center.
           The size does not change."""
        self.center_on_x_of(other_box)
        self.center_on_y_of(other_box)
    def same_as(self,other_box,edge,margin=0):
        """Set the specified edge of this box to be aligned with the
           same edge of other_box.  The size does not change.
        """
        if edge == LEFT:
            self.topleft[0] = other_box.left() + margin
        elif edge == RIGHT:
            self.topleft[0] = other_box.right() - margin
        elif edge == TOP:
            self.topleft[1] = other_box.top() + margin
        elif edge == BOTTOM:
            self.topleft[1] = other_box.bottom() - margin
        else:
            raise ValueError, "edge should only be plt.xxx where xxx is" \
                              " LEFT,RIGHT,TOP, or BOTTOM"
    def radial_offset_from(self,other_box,angle,margin=0):
        """ Move this box so that its center is aligned along a radial ray
            out of other_box's center at the specified angle (in radians),
            and its edge touches the appropriate edge of other_box.
            Optionally, margin specifies the size of the gap (along the ray)
            between the two boxes.
        """
        dist = other_box.radial(angle) + margin + self.radial(angle)
        new_center = other_box.center() + rotate((dist,0),(0,0),angle)
        self.center_on(point_object(new_center.astype(TYPE)))

    #------------------ Trim the edges of the box ----------------#
    def trim_top(self,amount,margin=0):
        """ Remove amount from the top edge of the box.  The size and
            topleft corner of the box are altered appropriately.  Margin
            specifies an additional amount to be removed.
        """
        self.topleft[1] = self.topleft[1] + amount
        self.set_height( self.height() - amount - margin)
    def trim_left(self,amount,margin=0):
        """ Remove amount from the left edge of the box.  The size and
            topleft corner of the box are altered appropriately.  Margin
            specifies an additional amount to be removed.
        """
        self.topleft[0] = self.topleft[0] + amount
        self.set_width( self.width() - amount - margin)
    def trim_right(self,amount,margin=0):
        """ Remove amount from the right edge of the box.  The size and
            is altered appropriately.  Margin specifies an additional amount
            to be removed.
        """
        self.set_width(self.width() - amount - margin)
    def trim_bottom(self,amount,margin=0):
        """ Remove amount from the bottom edge of the box.  The size
            is altered appropriately.  Margin specifies an additional
            amount to be removed.
        """
        self.set_height(self.height() - amount - margin)
    def trim_all(self,amount,margin=0):
        """ Remove amount from the all edges of the box.  The size and
            topleft corner of the bow are altered appropriately.  Margin
            specifies an additional amount to be removed.
        """
        self.trim_top(amount,margin)
        self.trim_bottom(amount,margin)
        self.trim_left(amount,margin)
        self.trim_bottom(amount,margin)

    def inflate(self,percent):
        """ Expand the box in all directions by the specified percentage.
            Values < 1 shrink the box.  The center of the box remains the same.
        """
        old_size = self.size()
        inflated = old_size * percent
        shift = .5 * (old_size - inflated)
        self.topleft = floor(self.topleft + shift).astype(TYPE)
        self.set_size(floor(inflated).astype(TYPE))

    #------------------ test point relationships ----------------#
    def contains(self,pos):
        l,r,t,b = self.left(),self.right(),self.top(),self.bottom()
        #print self.text, self.size(), l,r,t,b
        #print pos[0],pos[1]
        if ((l <= pos[0] <= r) and (t <= pos[1] <= b)):
            return 1
        return 0

class point_object(box_object):
    """ Useful for laying points (and boxes) in relation to one another.

        point_object is a degenerate case of a box_object that has
        zero size.  The set_size() method is not allowed for points. As
        a result, size altering methods such as set_height and trimming
        functions are not valid.  Also, the radial() method always returns
        zero.  Other than that, the standard box_object methods work.
        point_objects can also be used as arguments to box_object methods.
    """
    def __init__(self,pt):
        box_object.__init__(self,pt,(0,0))
    def radial(self,angle):
        return 0
    def set_size(self,sz):
        # this'll catch all set_size, trim_xxx and other inappropriate methods
        raise TypeError, "can't set the size of a point_object"

def bounding_points(objects):
    l = min(map(lambda x: x.left(),objects))
    t = min(map(lambda x: x.top(),objects))
    r = min(map(lambda x: x.right(),objects))
    b = min(map(lambda x: x.bottom(),objects))
    return (l,t),(r,b)

def bounding_box(objects):
    l = min(map(lambda x: x.left(),objects))
    t = min(map(lambda x: x.top(),objects))
    r = min(map(lambda x: x.right(),objects))
    b = min(map(lambda x: x.bottom(),objects))
    return box_object((l,t),(r-l,b-t))

#----------------------------------------------------------
#               Simple Property class
#----------------------------------------------------------

class property_object:
    """ Base class for graph object with properties like 'color', 'font', etc.

        Many object have a standard set of properties that describe the
        object.  Text objects, for example, have a color, font, and style.
        These attirbutes often have default values and perhaps only a range
        of acceptable values.  Every class derived from this one must have
        the variable "_attributes" defined at the class level.  The keys of
        this dictionary are the names of the class attributes.  The value
        for each key is a list with three entries.  The first is the default
        value for the attribute, the second is a list of acceptable values
        and the third is a short text description of the attribute.  FOr
        example:
          class text_object(property_class):
            _attributes = { 'color': ['black',['black','red','blue'],
                                      "The color of the text" ],
                            'style': ['normal',['normal','bold'],
                                      "The style of the text" ],}

        Currently only the first entry is used.  The second is rather limited
        in functionality, but might be useful for automatically generating
        dialog boxes.

        Graphite has a more flexible property system, but it is somewhat
        complex.  Zope also has a nice property structure.  If we run into
        major limitations with this 15 line implementation, we might look
        here for inspiration (or adoption...).

        There is no type safety enforced here which could cause so problems
        for unsuspecting users.  Maybe the optional typing of future Python
        versions will mitigate this.
    """
    def __init__(self, kw, **attr):
        attrs = {};attrs.update(kw);
        if attr: attrs.update(attr)
        for name, value in self._attributes.items():
            val = value[0]
            try:
                val = attrs[name]
            except KeyError: pass
            self.__dict__[name] = val
    def reset_default(self):
        """ Reset the objects attributes to their default values.
        """
        for name, value in self._attributes.items():
            self.__dict__[name] = value[0]

    def clone_properties(self,other):
        """ Reset the objects attributes to their default values.
        """
        for name in other._attributes.keys():
            self.__dict__[name] = other.__dict__[name]

#----------------------------------------------------------#
#-------------- Axis and Tick mark utilities --------------#
#----------------------------------------------------------#

def rotate(pts,center,angle):
    """ pts is a Nx2 array of N (x,y) point pairs.  The points
        are rotated counter-clockwise around a center (x,y) point
        the specified angle (in radians).
    """
    t_pts = asarray(pts) - asarray(center)
    transform = array( ((cos(angle),-sin(angle)),
                        (sin(angle), cos(angle))) )
    rotated = transpose(dot(transform, transpose(t_pts)))
    t_pts = around(rotated + center)
    return t_pts.astype(TYPE)

def log2(num):
    """ Log base 2 of a number ( or array)

        !! 1e-16 is here to prevent errors when log is 0
    """
    if is_number(num) and num == 0:
        num = num + 1e-16
    elif type(num) == type(array([])):
        putmask(num,equal(num,0.),1e-16)
    return log10(num)/log10(2)

def is_base2(range):
    " True if value is base 2 (2, 4, 8, 16, ...)"
    l = log2(range)
    return (l == floor(l) and l > 0.0)

def is_number(val):
    " Returns 1 if value is an integer or double, 0 otherwise."
    return (type(val) in [type(0.0),type(0)])

default_bounds = ['auto','auto','auto']
def auto_ticks(data_bounds, bounds_info = default_bounds):
    """ Find locations for axis tick marks.

        Calculate the location for tick marks on an axis. data_bounds is a
        sequence of 2 numbers specifying the maximum and minimum values of
        the data along this axis. bounds_info is a sequence of 3 values that
        specify how the axis end points and tick interval are calculated. An
        array of tick mark locations is returned from the function.  The
        first and last tick entries are the axis end points.

        data_bounds -- (lower,upper).  The maximum and minimum values of the
                       data long this axis.  If any of the settings in
                       bounds_info are 'auto' or 'fit', the axis properties
                       are calculated automatically from these settings.
        bounds_info -- (lower,upper,interval).  Each entry can either be
                       a numerical value or a string.  If a number,the axis
                       property is set to that value.  If the entry
                       is 'auto', the property is calculated automatically.
                       lower and upper can also be 'fit' in which case
                       the axis end points are set equal to the values
                       in data_bounds.
    """
    # pretty ugly code...
    # man, this needs some testing.

    # hmmm, all the nan stuff should have been handled before this
    # point...
    #from misc import nan_to_num, isinf
    #if is_number(bounds_info[0]): lower = nan_to_num(bounds_info[0])
    #else:                         lower = nan_to_num(data_bounds[0])
    #if is_number(bounds_info[1]): upper = nan_to_num(bounds_info[1])
    #else:                         upper = nan_to_num(data_bounds[1])
    #if is_number(bounds_info[2]): interval = nan_to_num(bounds_info[2])
    #else:                         interval = bounds_info[2]

    if is_number(bounds_info[0]): lower = bounds_info[0]
    else:                         lower = data_bounds[0]
    if is_number(bounds_info[1]): upper = bounds_info[1]
    else:                         upper = data_bounds[1]
    interval = bounds_info[2]

    #print 'raw input:', lower,upper,interval
    #print 'raw interval:', interval
    if interval in ['linear','auto']:
        rng = abs(upper - lower)
        if rng == 0.:
        # anything more intelligent to do here?
            interval = .5
            lower,upper = data_bounds + array((-.5,.5))
        if is_base2(rng) and is_base2(upper) and rng > 4:
            if rng == 2:
                interval = 1
            elif rng == 4:
                interval = 4
            else:
                interval = rng / 4 # maybe we want it 8
        else:
            interval = auto_interval((lower,upper))
    elif type(interval) in [type(0.0),type(0)]:
        pass
    else:
        #print 'interval: ', interval
        raise ValueError, interval + " is an unknown value for interval: " \
                          "  expects 'auto' or 'linear', or a number"

    # If the lower or upper bound are set to 'auto',
    # calculate them based on the newly chosen interval.
    #print 'interval:', interval
    auto_lower,auto_upper = auto_bounds(data_bounds,interval)
    if bounds_info[0] == 'auto':
        lower = auto_lower
    if bounds_info[1] == 'auto':
        upper = auto_upper

    # again, we shouldn't need this
    # cluge to handle inf values
    #if isinf(lower):
    #    lower = nan_to_num(lower) / 10
    #if isinf(upper):
    #    upper = nan_to_num(upper) / 10
    #if isinf(interval):
    #    interval = nan_to_num(interval) / 10
        # if the lower and upper bound span 0, make sure ticks
    # will hit exactly on zero.

    if lower < 0 and upper > 0:
        #print 'arrrgh',0,upper+interval,interval
        hi_ticks = arange(0,upper+interval,interval)
        low_ticks = - arange(interval,-lower+interval,interval)
        ticks = concatenate((low_ticks[::-1],hi_ticks))
    else:
        # othersize the ticks start and end on the lower and
        # upper values.
        ticks = arange(lower,upper+interval,interval)
    #cluge
    if len(ticks) < 2:
        ticks = array(((lower-lower*1e-7),lower))
    #print 'ticks:',ticks
    if bounds_info[0] == 'fit': ticks[0] = lower
    if bounds_info[1] == 'fit': ticks[-1] = upper
    return ticks


def format_tick_labels(ticks):
    """ Convert tick values to formatted strings.
        Definitely needs some work
    """
    return map(str,ticks)
    #print ticks
    #if equal(ticks,ticks.astype('l')):
    #    return map(str,ticks.astype('l'))
    #else:
    #    return map(str,ticks)



def calc_bound(end_point,interval,end):
    """ Find an axis end point that includes the the value end_point.  If the
        tick mark interval results in a tick mark hitting directly on the
        end_point, end_point is returned.  Otherwise, the location of the tick
        mark just past the end_point is returned. end is 'lower' or 'upper' to
        specify whether end_point is at the lower or upper end of the axis.
    """
    quotient,remainder = divmod(end_point,interval)
    if not remainder: return end_point

    c1 = axis_bound = (quotient + 1) * interval
    c2 = axis_bound = (quotient) * interval
    if end == 'upper': return max(c1,c2)
    if end == 'lower': return min(c1,c2)


def auto_bounds(data_bounds,interval):
    """ Calculate an appropriate upper and lower bounds for the axis from
        the the data_bounds (lower, upper) and the given axis interval.  The
        boundaries will either hit exactly on the lower and upper values
        or on the tick mark just beyond the lower and upper values.
    """
    data_lower,data_upper = data_bounds
    lower = calc_bound(data_lower,interval,'lower')
    upper = calc_bound(data_upper,interval,'upper')
    return array((lower,upper))

def auto_interval(data_bounds):
    """ Calculate the tick intervals for a graph axis.

        Description:
        The boundaries for the data to be plotted on the axis are:
            data_bounds = (lower,upper)

        A choice is made between 3 to 9 ticks marks (including end points)
        and tick intervals at 1, 2, 2.5, 5, 10, 20, ...

        Returns:
        interval -- float. tick mark interval for axis
    """
    range = float(data_bounds[1]) - float(data_bounds[0])
    # We'll choose from between 2 and 8 tick marks
    # Favortism is given to more ticks:
    #   Note reverse order and see CLUGE below...
    divisions = arange(8,2.,-1.) #(7,6,...,3)
    # Calculate the intervals for the divisions
    candidate_intervals = range / divisions
    # Get magnitudes and mantissas for each candidate
    magnitudes = 10.**floor(log10(candidate_intervals))
    mantissas = candidate_intervals / magnitudes

    # list of "pleasing" intervals between ticks on graph
    # only first magnitude listed, higher mags others inferred
    magic_intervals = array((1.,2.,2.5,5.,10.))
    # calculate the absolute differences between the candidates
    # (with mag removed) and the magic intervals
    differences = abs(magic_intervals[:,newaxis] - mantissas)

    # Find the division and magic interval combo
    # that produce the smallest differences.
    # also:
    # CLUGE: argsort doesn't preserve the order of
    # equal values, so we subtract a small , index
    # dependent amount from each difference to
    # force correct ordering
    sh = shape(differences)
    small = 2.2e-16 *arange(sh[1]) * arange(sh[0])[:,newaxis]
    small = small[::-1,::-1] #reverse order
    differences = differences - small
    # ? Numeric should allow keyword "axis" ? comment out for now
    #best_mantissa = minimum.reduce(differences,axis=0)
    #best_magic = minimum.reduce(differences,axis=-1)
    best_mantissa = minimum.reduce(differences,0)
    best_magic = minimum.reduce(differences,-1)
    magic_index = argsort(best_magic)[0]
    mantissa_index = argsort(best_mantissa)[0]
    # The best interval is the magic_interval
    # multiplied by the magnitude of the best mantissa
    interval = magic_intervals[magic_index]
    magnitude = magnitudes[mantissa_index]
    #print differences
    #print 'results:', magic_index, mantissa_index,interval, magnitude
    #print 'returned:',interval*magnitude
    result = interval*magnitude
    if result == 0.0:
        result = limits.float_epsilon
    return result