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.data.xyz;
034
035import org.jfree.chart3d.data.Range;
036import org.jfree.chart3d.data.function.Function3D;
037
038/**
039 * A collection of utility methods related to {@link XYZDataset}.
040 */
041public class XYZDatasetUtils {
042    
043    /**
044     * Creates an {@link XYZDataset} by sampling a {@link Function3D} over
045     * a specified range.
046     * 
047     * @param f  the function ({@code null} not permitted).
048     * @param key  the series key ({@code null} not permitted).
049     * @param xrange  the range of x values ({@code null} not permitted).
050     * @param xcount  the number of x samples (must be at least 2).
051     * @param zrange  the range of z values ({@code null} not permitted).
052     * @param zcount  the number of z-samples (must be at least 2).
053     * 
054     * @return A dataset containing sampled values from the function.
055     */
056    public static XYZDataset<String> sampleFunction(Function3D f, String key, 
057            Range xrange, double xcount, Range zrange, double zcount) {
058        return sampleFunction(f, key, xrange.getMin(), xrange.getMax(),
059                xcount, zrange.getMin(), zrange.getMax(), zcount);
060    }
061    
062    /**
063     * Creates an {@link XYZDataset} by sampling a {@link Function3D} over
064     * a specified range.
065     * 
066     * @param f  the function ({@code null} not permitted).
067     * @param key  the series key ({@code null} not permitted).
068     * @param xmin  the lower bound of the x-range.
069     * @param xmax  the upper bound of the x-range.
070     * @param xcount  the number of x samples (must be at least 2).
071     * @param zmin  the lower bound of the z-range.
072     * @param zmax  the upper bound of the z-range.
073     * @param zcount  the number of z-samples (must be at least 2).
074     * 
075     * @return A dataset containing sampled values from the function.
076     */
077    public static XYZDataset<String> sampleFunction(Function3D f, String key, 
078            double xmin, double xmax, double xcount, 
079            double zmin, double zmax, double zcount) {
080        XYZSeries<String> s = new XYZSeries<>(key);
081        for (double x = xmin; x <= xmax; x += (xmax - xmin) / xcount) {
082            for (double z = zmin; z <= zmax; z += (zmax - zmin) / zcount) {
083                s.add(x, f.getValue(x, z), z);
084            }
085        }
086        XYZSeriesCollection<String> dataset = new XYZSeriesCollection<>();
087        dataset.add(s);
088        return dataset;
089    }
090    
091}