001/* =========================================================== 002 * Orson Charts : a 3D chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C)opyright 2013-2016, by Object Refinery Limited. All rights reserved. 006 * 007 * http://www.object-refinery.com/orsoncharts/index.html 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 com.orsoncharts.renderer.xyz; 034 035import java.awt.Color; 036import java.io.Serializable; 037 038import com.orsoncharts.Chart3DFactory; 039import com.orsoncharts.axis.Axis3D; 040import com.orsoncharts.data.xyz.XYZDataset; 041import com.orsoncharts.data.xyz.XYZItemKey; 042import com.orsoncharts.plot.XYZPlot; 043import com.orsoncharts.graphics3d.Dimension3D; 044import com.orsoncharts.graphics3d.Object3D; 045import com.orsoncharts.graphics3d.Offset3D; 046import com.orsoncharts.graphics3d.World; 047import com.orsoncharts.renderer.Renderer3DChangeEvent; 048import com.orsoncharts.util.ArgChecks; 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 * <object id="ABC" data="../../../../doc-files/ScatterPlot3DDemo2.svg" 055 * type="image/svg+xml" width="500" height="359"></object> 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 ArgChecks.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 ArgChecks.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 public void composeItem(XYZDataset dataset, int series, int item, 152 World world, Dimension3D dimensions, double xOffset, double yOffset, 153 double zOffset) { 154 155 double x = dataset.getX(series, item); 156 double y = dataset.getY(series, item); 157 double z = dataset.getZ(series, item); 158 159 XYZPlot plot = getPlot(); 160 Axis3D xAxis = plot.getXAxis(); 161 Axis3D yAxis = plot.getYAxis(); 162 Axis3D zAxis = plot.getZAxis(); 163 164 double delta = this.size / 2.0; 165 Dimension3D dim = plot.getDimensions(); 166 double xx = xAxis.translateToWorld(x, dim.getWidth()); 167 double xmin = Math.max(0.0, xx - delta); 168 double xmax = Math.min(dim.getWidth(), xx + delta); 169 double yy = yAxis.translateToWorld(y, dim.getHeight()); 170 double ymin = Math.max(0.0, yy - delta); 171 double ymax = Math.min(dim.getHeight(), yy + delta); 172 double zz = zAxis.translateToWorld(z, dim.getDepth()); 173 double zmin = Math.max(0.0, zz - delta); 174 double zmax = Math.min(dim.getDepth(), zz + delta); 175 if ((xmin >= xmax) || (ymin >= ymax) || (zmin >= zmax)) { 176 return; 177 } 178 Color color = getColorSource().getColor(series, item); 179 double cx = (xmax + xmin) / 2.0 + xOffset; 180 double cy = (ymax + ymin) / 2.0 + yOffset; 181 double cz = (zmax + zmin) / 2.0 + zOffset; 182 Object3D cube = Object3D.createBox(cx, xmax - xmin, cy, ymax - ymin, 183 cz, zmax - zmin, color); 184 Comparable<?> seriesKey = dataset.getSeriesKey(series); 185 XYZItemKey itemKey = new XYZItemKey(seriesKey, item); 186 cube.setProperty(Object3D.ITEM_KEY, itemKey); 187 world.add(cube); 188 189 if (getItemLabelGenerator() != null) { 190 String label = getItemLabelGenerator().generateItemLabel(dataset, 191 seriesKey, item); 192 if (label != null) { 193 double dx = this.itemLabelOffsetPercent.getDX() * this.size; 194 double dy = this.itemLabelOffsetPercent.getDY() * this.size; 195 double dz = this.itemLabelOffsetPercent.getDZ() * this.size; 196 Object3D labelObj = Object3D.createLabelObject(label, 197 getItemLabelFont(), getItemLabelColor(), 198 getItemLabelBackgroundColor(), cx + dx, cy + dy, 199 cz + dz, false, true); 200 labelObj.setProperty(Object3D.ITEM_KEY, itemKey); 201 world.add(labelObj); 202 } 203 } 204 205 } 206 207 /** 208 * Tests this renderer for equality with an arbitrary object. 209 * 210 * @param obj the object to test ({@code null} permitted). 211 * 212 * @return A boolean. 213 */ 214 @Override 215 public boolean equals(Object obj) { 216 if (obj == this) { 217 return true; 218 } 219 if (!(obj instanceof ScatterXYZRenderer)) { 220 return false; 221 } 222 ScatterXYZRenderer that = (ScatterXYZRenderer) obj; 223 if (this.size != that.size) { 224 return false; 225 } 226 if (!this.itemLabelOffsetPercent.equals(that.itemLabelOffsetPercent)) { 227 return false; 228 } 229 return super.equals(obj); 230 } 231}