source: nanovis/trunk/Axis.cpp @ 6369

/* -*- mode: c++; c-basic-offset: 4; indent-tabs-mode: nil -*- */
/*
 * Copyright (c) 2004-2013  HUBzero Foundation, LLC
 *
 * Authors:
 *   George A. Howlett <gah@purdue.edu>
 *   Leif Delgass <ldelgass@purdue.edu>
 */
#include <string>

#include <stdlib.h>
#include <stdio.h>
#include <math.h>
#include <float.h>
#include <string.h>

#include "Axis.h"
#include "Trace.h"

using namespace nv;

inline double EXP10(double x) {
    return pow(10.0, x);
}

inline int ROUND(double x) {
    return (int)round(x);
}

inline double UROUND(double x, double u) {
    return (ROUND((x)/(u)))*u;
}

inline double UCEIL(double x, double u) {
    return (ceil((x)/(u)))*u;
}

inline double UFLOOR(double x, double u) {
    return (floor((x)/(u)))*u;
}

/**
 * Reference: Paul Heckbert, "Nice Numbers for Graph Labels",
 *            Graphics Gems, pp 61-63.  
 *
 * Finds a "nice" number approximately equal to x.
 */
static double
niceNum(double x,
        int round)              /* If non-zero, round. Otherwise take ceiling
                                 * of value. */
{
    double expt;                /* Exponent of x */
    double frac;                /* Fractional part of x */
    double nice;                /* Nice, rounded fraction */

    expt = floor(log10(x));
    frac = x / EXP10(expt);     /* between 1 and 10 */
    if (round) {
        if (frac < 1.5) {
            nice = 1.0;
        } else if (frac < 3.0) {
            nice = 2.0;
        } else if (frac < 7.0) {
            nice = 5.0;
        } else {
            nice = 10.0;
        }
    } else {
        if (frac <= 1.0) {
            nice = 1.0;
        } else if (frac <= 2.0) {
            nice = 2.0;
        } else if (frac <= 5.0) {
            nice = 5.0;
        } else {
            nice = 10.0;
        }
    }
    return nice * EXP10(expt);
}

void 
Ticks::setTicks()
{
    _numTicks = 0;
    _ticks = new float[_nSteps];
    // Start from smallest axis tick
    double value = _initial;
    for (unsigned int i = 0; i < _nSteps; i++) {
        value = _initial + (_step * i);
        _ticks[i] = UROUND(value, _step);
    }
    _numTicks = _nSteps;
}

Axis::Axis(const char *title) :
    _title(title),
    _tightMin(false),
    _tightMax(false),
    _reqStep(0.0),
    _valueMin(DBL_MAX),
    _valueMax(-DBL_MAX),
    _min(DBL_MAX),
    _max(-DBL_MAX),
    _major(5),
    _minor(2)
{
}

/**
 * \brief Determines if a value lies within a given range.
 *
 * The value is normalized by the current axis range. If the normalized
 * value is between [0.0,1.0] then it's in range.  The value is compared
 * to 0 and 1., where 0.0 is the minimum and 1.0 is the maximum.
 * DBL_EPSILON is the smallest number that can be represented on the host
 * machine, such that (1.0 + epsilon) != 1.0.
 *
 * Please note, *max* can't equal *min*.
 *
 * \return If the value is within the interval [min,max], 1 is returned; 0
 * otherwise.
 */
bool
Axis::inRange(double x)
{
    if ((_max - _min) < DBL_EPSILON) {
        return (fabs(_max - x) >= DBL_EPSILON);
    } else {
        x = map(x);
        return ((x >= -DBL_EPSILON) && ((x - 1.0) < DBL_EPSILON));
    }
}

void
Axis::fixRange(double min, double max)
{
    if (min == DBL_MAX) {
        min = 0.0;
    }
    if (max == -DBL_MAX) {
        max = 1.0;
    }
    if (min >= max) {
        // No range, so pick a default
        if (min == 0.0) {
            min = 0.0, max = 1.0;
        } else {
            max = min + (fabs(min) * 0.1);
        }
    }

    _valueMin = min;
    _valueMax = max;
}

/**
 * \brief Determine the units of a linear scaled axis.
 *
 * The axis limits are either the range of the data values mapped
 * to the axis (autoscaled), or the values specified by the -min
 * and -max options (manual).
 *
 * If autoscaled, the smallest and largest major ticks will
 * encompass the range of data values.  If the -loose option is
 * selected, the next outer ticks are choosen.  If tight, the
 * ticks are at or inside of the data limits are used.
 *
 * If manually set, the ticks are at or inside the data limits
 * are used.  This makes sense for zooming.  You want the
 * selected range to represent the next limit, not something a
 * bit bigger.
 *
 * Note: I added an "always" value to the -loose option to force
 * the manually selected axes to be loose. It's probably
 * not a good idea.
 *
 * <pre>
 *          maxY
 *            |    units = magnitude (of least significant digit)
 *            |    high  = largest unit tick < max axis value
 *      high _|    low   = smallest unit tick > min axis value
 *            |
 *            |    range = high - low
 *            |    # ticks = greatest factor of range/units
 *           _|
 *        U   |
 *        n   |
 *        i   |
 *        t  _|
 *            |
 *            |
 *            |
 *       low _|
 *            |
 *            |_minX________________maxX__
 *            |   |       |      |       |
 *     minY  low                        high
 *           minY
 *
 *      numTicks = Number of ticks
 *      min = Minimum value of axis
 *      max = Maximum value of axis
 *      range = Range of values (max - min)
 *
 * </pre>
 *
 * Side Effects:
 *      The axis tick information is set.  The actual tick values will
 *      be generated later.
 */
void
Axis::linearScale()
{
    double tickMin = 0., tickMax = 0.;
    double step = 1.0;
    unsigned int nTicks = 0;

    if (_valueMin < _valueMax) {
        double range = _valueMax - _valueMin;
        /* Calculate the major tick stepping. */
        if (_reqStep > 0.0) {
            /* An interval was designated by the user.  Keep scaling it until
             * it fits comfortably within the current range of the axis.  */
            step = _reqStep;
            while ((2 * step) >= range) {
                step *= 0.5;
            }
        } else {
            range = niceNum(range, 0);
            step = niceNum(range / _major.reqNumTicks, 1);
        }
        
        /* Find the outer tick values. Add 0.0 to prevent getting -0.0. */
        tickMin = floor(_valueMin / step) * step + 0.0;
        tickMax = ceil(_valueMax / step) * step + 0.0;
        
        nTicks = ROUND((tickMax - tickMin) / step) + 1;
    } 
    _major.setValues(tickMin, step, nTicks);

    /*
     * The limits of the axis are either the range of the data ("tight") or at
     * the next outer tick interval ("loose").  The looseness or tightness has
     * to do with how the axis fits the range of data values.
     */
    _min = _tightMin ? _valueMin : tickMin;
    _max = _tightMax ? _valueMax : tickMax;

    /* Now calculate the minor tick step and number. */

    if (_minor.reqNumTicks > 0) {
        nTicks = _minor.reqNumTicks - 1;
        step = 1.0 / (nTicks + 1);
    } else {
        nTicks = 0;             /* No minor ticks. */
        step = 0.5;             /* Don't set the minor tick interval to
                                 * 0.0. It makes the GenerateTicks routine
                                 * create minor log-scale tick marks.  */
    }
    _minor.setValues(step, step, nTicks);
}

/**
 * \brief This sets the data range of the axis.
 */
void
Axis::setRange(double min, double max)
{
    // set valueMin/Max (overridden by requested min/max if present)
    fixRange(min, max);
    // Set steps
    linearScale();
    // Fill ticks float arrays based on spacing
    _major.sweepTicks();
    _minor.sweepTicks();
    // Copy to linked lists
    makeTicks();
}

/**
 * \brief Copy tick values to major/minor linked lists, skipping duplicate values
 */
void
Axis::makeTicks()
{
    _major.reset();
    _minor.reset();
    for (int i = 0; i < _major.numTicks(); i++) {
        double t1 = _major.tick(i);
        /* Minor ticks */
        for (int j = 0; j < _minor.numTicks(); j++) {
            double t2 = t1 + (_major.step() * _minor.tick(j));
            if (!inRange(t2)) {
                continue;
            }
            if (t1 == t2) {
                continue;        // Don't add duplicate minor ticks.
            }
            _minor.append(t2);
        }
        if (!inRange(t1)) {
            continue;
        }
        _major.append(t1);
    }
}

/**
 * \brief Map world coordinate [_min,_max] to normalized coordinate [0,1]
 */
double
Axis::map(double x)
{
    x = (x - _min) / (_max - _min);
    return x;
}

/**
 * \brief Map normalized coordinate [0,1] to world coordinate [_min,_max]
 */
double
Axis::invMap(double x)
{
    x = (x * (_max - _min)) + _min;
    return x;
}