001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2014, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * -------------------
028 * HeatMapDataset.java
029 * -------------------
030 * (C) Copyright 2009-2014, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes:
036 * --------
037 * 28-Jan-2009 : Version 1 (DG);
038 *
039 */
040
041package org.jfree.data.general;
042
043/**
044 * A dataset that represents a rectangular grid of (x, y, z) values.  The x
045 * and y values appear at regular intervals in the dataset, while the z-values
046 * can take any value (including <code>null</code> for unknown values).
047 *
048 * @since 1.0.13
049 */
050public interface HeatMapDataset {
051
052    /**
053     * Returns the number of x values across the width of the dataset.  The
054     * values are evenly spaced between {@link #getMinimumXValue()} and
055     * {@link #getMaximumXValue()}.
056     * 
057     * @return The number of x-values (always &gt; 0).
058     */
059    public int getXSampleCount();
060
061    /**
062     * Returns the number of y values (or samples) for the dataset.  The
063     * values are evenly spaced between {@link #getMinimumYValue()} and
064     * {@link #getMaximumYValue()}.
065     *
066     * @return The number of y-values (always &gt; 0).
067     */
068    public int getYSampleCount();
069
070    /**
071     * Returns the lowest x-value represented in this dataset.  A requirement
072     * of this interface is that this method must never return infinite or
073     * Double.NAN values.
074     *
075     * @return The lowest x-value represented in this dataset.
076     */
077    public double getMinimumXValue();
078
079    /**
080     * Returns the highest x-value represented in this dataset.  A requirement
081     * of this interface is that this method must never return infinite or
082     * Double.NAN values.
083     *
084     * @return The highest x-value represented in this dataset.
085     */
086    public double getMaximumXValue();
087
088    /**
089     * Returns the lowest y-value represented in this dataset.  A requirement
090     * of this interface is that this method must never return infinite or
091     * Double.NAN values.
092     *
093     * @return The lowest y-value represented in this dataset.
094     */
095    public double getMinimumYValue();
096
097    /**
098     * Returns the highest y-value represented in this dataset.  A requirement
099     * of this interface is that this method must never return infinite or
100     * Double.NAN values.
101     *
102     * @return The highest y-value represented in this dataset.
103     */
104    public double getMaximumYValue();
105
106    /**
107     * A convenience method that returns the x-value for the given index.
108     * 
109     * @param xIndex  the xIndex.
110     * 
111     * @return The x-value.
112     */
113    public double getXValue(int xIndex);
114
115    /**
116     * A convenience method that returns the y-value for the given index.
117     * 
118     * @param yIndex  the yIndex.
119     * 
120     * @return The y-value.
121     */
122    public double getYValue(int yIndex);
123
124    /**
125     * Returns the z-value at the specified sample position in the dataset.
126     * For a missing or unknown value, this method should return Double.NAN.
127     *
128     * @param xIndex  the position of the x sample in the dataset.
129     * @param yIndex  the position of the y sample in the dataset.
130     *
131     * @return The z-value.
132     */
133    public double getZValue(int xIndex, int yIndex);
134
135    /**
136     * Returns the z-value at the specified sample position in the dataset.
137     * This method can return <code>null</code> to indicate a missing/unknown
138     * value.
139     * <br><br>
140     * Bear in mind that the class implementing this interface may
141     * store its data using primitives rather than objects, so calling this
142     * method may require a new <code>Number</code> object to be allocated...
143     * for this reason, it is generally preferable to use the
144     * {@link #getZValue(int, int)} method unless you *know* that the dataset
145     * implementation stores the z-values using objects.
146     *
147     * @param xIndex  the position of the x sample in the dataset.
148     * @param yIndex  the position of the y sample in the dataset.
149     *
150     * @return The z-value (possibly <code>null</code>).
151     */
152    public Number getZ(int xIndex, int yIndex);
153
154}