1 /* =========================================================== 2 * JFreeChart : a free chart library for the Java(tm) platform 3 * =========================================================== 4 * 5 * (C) Copyright 2000-2013, by Object Refinery Limited and Contributors. 6 * 7 * Project Info: http://www.jfree.org/jfreechart/index.html 8 * 9 * This library is free software; you can redistribute it and/or modify it 10 * under the terms of the GNU Lesser General Public License as published by 11 * the Free Software Foundation; either version 2.1 of the License, or 12 * (at your option) any later version. 13 * 14 * This library is distributed in the hope that it will be useful, but 15 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 16 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 17 * License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with this library; if not, write to the Free Software 21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 22 * USA. 23 * 24 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 25 * Other names may be trademarks of their respective owners.] 26 * 27 * ------------------- 28 * HeatMapDataset.java 29 * ------------------- 30 * (C) Copyright 2009, by Object Refinery Limited. 31 * 32 * Original Author: David Gilbert (for Object Refinery Limited); 33 * Contributor(s): -; 34 * 35 * Changes: 36 * -------- 37 * 28-Jan-2009 : Version 1 (DG); 38 * 39 */ 40 41 package org.jfree.data.general; 42 43 /** 44 * A dataset that represents a rectangular grid of (x, y, z) values. The x 45 * and y values appear at regular intervals in the dataset, while the z-values 46 * can take any value (including <code>null</code> for unknown values). 47 * 48 * @since 1.0.13 49 */ 50 public interface HeatMapDataset { 51 52 /** 53 * Returns the number of x values across the width of the dataset. The 54 * values are evenly spaced between {@link #getMinimumXValue()} and 55 * {@link #getMaximumXValue()}. 56 * 57 * @return The number of x-values (always > 0). 58 */ getXSampleCount()59 public int getXSampleCount(); 60 61 /** 62 * Returns the number of y values (or samples) for the dataset. The 63 * values are evenly spaced between {@link #getMinimumYValue()} and 64 * {@link #getMaximumYValue()}. 65 * 66 * @return The number of y-values (always > 0). 67 */ getYSampleCount()68 public int getYSampleCount(); 69 70 /** 71 * Returns the lowest x-value represented in this dataset. A requirement 72 * of this interface is that this method must never return infinite or 73 * Double.NAN values. 74 * 75 * @return The lowest x-value represented in this dataset. 76 */ getMinimumXValue()77 public double getMinimumXValue(); 78 79 /** 80 * Returns the highest x-value represented in this dataset. A requirement 81 * of this interface is that this method must never return infinite or 82 * Double.NAN values. 83 * 84 * @return The highest x-value represented in this dataset. 85 */ getMaximumXValue()86 public double getMaximumXValue(); 87 88 /** 89 * Returns the lowest y-value represented in this dataset. A requirement 90 * of this interface is that this method must never return infinite or 91 * Double.NAN values. 92 * 93 * @return The lowest y-value represented in this dataset. 94 */ getMinimumYValue()95 public double getMinimumYValue(); 96 97 /** 98 * Returns the highest y-value represented in this dataset. A requirement 99 * 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 */ getMaximumYValue()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 */ getXValue(int xIndex)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 */ getYValue(int yIndex)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 */ getZValue(int xIndex, int yIndex)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 */ getZ(int xIndex, int yIndex)152 public Number getZ(int xIndex, int yIndex); 153 154 } 155