001/* =========================================================== 002 * Orson Charts : a 3D chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C)opyright 2013-2022, by David Gilbert. All rights reserved. 006 * 007 * https://github.com/jfree/orson-charts 008 * 009 * This program is free software: you can redistribute it and/or modify 010 * it under the terms of the GNU General Public License as published by 011 * the Free Software Foundation, either version 3 of the License, or 012 * (at your option) any later version. 013 * 014 * This program is distributed in the hope that it will be useful, 015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 017 * GNU General Public License for more details. 018 * 019 * You should have received a copy of the GNU General Public License 020 * along with this program. If not, see <http://www.gnu.org/licenses/>. 021 * 022 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 023 * Other names may be trademarks of their respective owners.] 024 * 025 * If you do not wish to be bound by the terms of the GPL, an alternative 026 * commercial license can be purchased. For details, please see visit the 027 * Orson Charts home page: 028 * 029 * http://www.object-refinery.com/orsoncharts/index.html 030 * 031 */ 032 033package org.jfree.chart3d.renderer.xyz; 034 035import java.awt.Color; 036import java.io.Serializable; 037 038import org.jfree.chart3d.Chart3DFactory; 039import org.jfree.chart3d.axis.Axis3D; 040import org.jfree.chart3d.data.xyz.XYZDataset; 041import org.jfree.chart3d.data.xyz.XYZItemKey; 042import org.jfree.chart3d.graphics3d.Dimension3D; 043import org.jfree.chart3d.graphics3d.Object3D; 044import org.jfree.chart3d.graphics3d.Offset3D; 045import org.jfree.chart3d.graphics3d.World; 046import org.jfree.chart3d.internal.Args; 047import org.jfree.chart3d.plot.XYZPlot; 048import org.jfree.chart3d.renderer.Renderer3DChangeEvent; 049 050/** 051 * A renderer for 3D scatter plots. This renderer is used with an 052 * {@link XYZPlot} and any {@link XYZDataset} instance. Here is a sample: 053 * <div> 054 * <img src="../../../../../../doc-files/ScatterPlot3DDemo2.svg" 055 * alt="ScatterPlot3DDemo2.svg" width="500" height="359"> 056 * </div> 057 * (refer to {@code ScatterPlot3DDemo2.java} for the code to generate 058 * the above chart). 059 * <br><br> 060 * TIP: to create a chart using this renderer, you can use the 061 * {@link Chart3DFactory#createScatterChart(String, String, XYZDataset, String, String, String)} 062 * method. 063 * <br><br> 064 * NOTE: This class is serializable, but the serialization format is subject 065 * to change in future releases and should not be relied upon for persisting 066 * instances of this class. 067 */ 068@SuppressWarnings("serial") 069public class ScatterXYZRenderer extends AbstractXYZRenderer 070 implements XYZRenderer, Serializable { 071 072 /** The size of the cubes to render for each data point (in world units). */ 073 private double size; 074 075 /** The offsets for item labels, as a percentage of the size. */ 076 private Offset3D itemLabelOffsetPercent; 077 078 /** 079 * Creates a new instance with default attribute values. 080 */ 081 public ScatterXYZRenderer() { 082 super(); 083 this.size = 0.10; 084 this.itemLabelOffsetPercent = new Offset3D(0.0, 1.0, 0.0); 085 } 086 087 /** 088 * Returns the size of the cubes (in world units) used to display each data 089 * item. The default value is {@code 0.10}. 090 * 091 * @return The size (in world units). 092 */ 093 public double getSize() { 094 return this.size; 095 } 096 097 /** 098 * Sets the size (in world units) of the cubes used to represent each data 099 * item and sends a {@link Renderer3DChangeEvent} to all registered 100 * listeners. 101 * 102 * @param size the size (in world units, must be positive). 103 */ 104 public void setSize(double size) { 105 Args.positiveRequired(size, "size"); 106 this.size = size; 107 fireChangeEvent(true); 108 } 109 110 /** 111 * Returns the item label offsets. 112 * 113 * @return The item label offsets (never {@code null}). 114 * 115 * @since 1.3 116 */ 117 public Offset3D getItemLabelOffsetPercent() { 118 return this.itemLabelOffsetPercent; 119 } 120 121 /** 122 * Sets the item label offsets and sends a change event to all registered 123 * listeners. 124 * 125 * @param offset the new offset ({@code null} not permitted). 126 * 127 * @since 1.3 128 */ 129 public void setItemLabelOffsetPercent(Offset3D offset) { 130 Args.nullNotPermitted(offset, "offset"); 131 this.itemLabelOffsetPercent = offset; 132 fireChangeEvent(true); 133 } 134 135 /** 136 * Constructs and places one item from the specified dataset into the given 137 * world. The {@link XYZPlot} class will iterate over its dataset and 138 * and call this method for each item (in other words, you don't need to 139 * call this method directly). 140 * 141 * @param dataset the dataset ({@code null} not permitted). 142 * @param series the series index. 143 * @param item the item index. 144 * @param world the world ({@code null} not permitted). 145 * @param dimensions the dimensions ({@code null} not permitted). 146 * @param xOffset the x-offset. 147 * @param yOffset the y-offset. 148 * @param zOffset the z-offset. 149 */ 150 @Override 151 @SuppressWarnings("unchecked") 152 public void composeItem(XYZDataset dataset, int series, int item, 153 World world, Dimension3D dimensions, double xOffset, double yOffset, 154 double zOffset) { 155 156 double x = dataset.getX(series, item); 157 double y = dataset.getY(series, item); 158 double z = dataset.getZ(series, item); 159 160 XYZPlot plot = getPlot(); 161 Axis3D xAxis = plot.getXAxis(); 162 Axis3D yAxis = plot.getYAxis(); 163 Axis3D zAxis = plot.getZAxis(); 164 165 double delta = this.size / 2.0; 166 Dimension3D dim = plot.getDimensions(); 167 double xx = xAxis.translateToWorld(x, dim.getWidth()); 168 double xmin = Math.max(0.0, xx - delta); 169 double xmax = Math.min(dim.getWidth(), xx + delta); 170 double yy = yAxis.translateToWorld(y, dim.getHeight()); 171 double ymin = Math.max(0.0, yy - delta); 172 double ymax = Math.min(dim.getHeight(), yy + delta); 173 double zz = zAxis.translateToWorld(z, dim.getDepth()); 174 double zmin = Math.max(0.0, zz - delta); 175 double zmax = Math.min(dim.getDepth(), zz + delta); 176 if ((xmin >= xmax) || (ymin >= ymax) || (zmin >= zmax)) { 177 return; 178 } 179 Color color = getColorSource().getColor(series, item); 180 double cx = (xmax + xmin) / 2.0 + xOffset; 181 double cy = (ymax + ymin) / 2.0 + yOffset; 182 double cz = (zmax + zmin) / 2.0 + zOffset; 183 Object3D cube = Object3D.createBox(cx, xmax - xmin, cy, ymax - ymin, 184 cz, zmax - zmin, color); 185 Comparable<?> seriesKey = dataset.getSeriesKey(series); 186 XYZItemKey itemKey = new XYZItemKey(seriesKey, item); 187 cube.setProperty(Object3D.ITEM_KEY, itemKey); 188 world.add(cube); 189 190 if (getItemLabelGenerator() != null) { 191 String label = getItemLabelGenerator().generateItemLabel(dataset, 192 seriesKey, item); 193 if (label != null) { 194 double dx = this.itemLabelOffsetPercent.getDX() * this.size; 195 double dy = this.itemLabelOffsetPercent.getDY() * this.size; 196 double dz = this.itemLabelOffsetPercent.getDZ() * this.size; 197 Object3D labelObj = Object3D.createLabelObject(label, 198 getItemLabelFont(), getItemLabelColor(), 199 getItemLabelBackgroundColor(), cx + dx, cy + dy, 200 cz + dz, false, true); 201 labelObj.setProperty(Object3D.ITEM_KEY, itemKey); 202 world.add(labelObj); 203 } 204 } 205 206 } 207 208 /** 209 * Tests this renderer for equality with an arbitrary object. 210 * 211 * @param obj the object to test ({@code null} permitted). 212 * 213 * @return A boolean. 214 */ 215 @Override 216 public boolean equals(Object obj) { 217 if (obj == this) { 218 return true; 219 } 220 if (!(obj instanceof ScatterXYZRenderer)) { 221 return false; 222 } 223 ScatterXYZRenderer that = (ScatterXYZRenderer) obj; 224 if (this.size != that.size) { 225 return false; 226 } 227 if (!this.itemLabelOffsetPercent.equals(that.itemLabelOffsetPercent)) { 228 return false; 229 } 230 return super.equals(obj); 231 } 232}