001 /* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2009, 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 * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
025 * in the United States and other countries.]
026 *
027 * -------------------
028 * HeatMapDataset.java
029 * -------------------
030 * (C) Copyright 2009, 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
041 package 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 */
050 public 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 > 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 > 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 }