// 1. Build a Plot
ScatterPlot plot = ScatterPlot.of(points, 'o');

// 2. Wrap it in a Figure (bounds are inferred automatically)
Figure figure = plot.figure();

// 3. Optionally configure the Figure
figure.setTitle("My Scatter Plot")
      .setAxisLabels("X", "Y");

// 4. Display in a window
figure.show();                      // convenience wrapper
// --- or equivalently ---
new FigurePane(figure).window();

figure.show();                      // SwingUtilities.invokeLater internally

FigurePane pane = new FigurePane(figure);
myPanel.add(pane, BorderLayout.CENTER);

BufferedImage img = figure.toBufferedImage(1280, 960);
ImageIO.write(img, "png", new File("plot.png"));

Figure fig = new Figure(lowerBound, upperBound);   // explicit bounds
Figure fig = new Figure(lowerBound, upperBound, false); // no bound-padding

fig.setTitle("Iris Dataset")
   .setTitleFont(new Font("SansSerif", Font.BOLD, 18))
   .setTitleColor(Color.DARK_GRAY)
   .setMargin(0.12)               // fraction of canvas size; must be in (0, 0.3)
   .setLegendVisible(true);

fig.add(aPlot);           // Plot subclass — bounds are extended automatically
fig.add(aShape);          // any Shape (Label, GridLabel, …) — bounds unchanged
fig.remove(aPlot);
fig.clear();              // remove all shapes

fig.addPropertyChangeListener(e -> System.out.println(e.getPropertyName()));

Color red   = Palette.web("red");
Color coral = Palette.web("#ff6347");
Color semi  = Palette.web("rgba(255,99,71,0.5)");   // 50% opacity
Color hsl   = Palette.web("hsl(9, 100%, 64%)");
Color hex0x = Palette.web("0xff6347");

Palette.RED   Palette.GREEN   Palette.BLUE     Palette.CYAN
Palette.MAGENTA  Palette.YELLOW  Palette.BLACK  Palette.WHITE
Palette.DARK_GRAY  Palette.LIGHT_GRAY

Color[] jet     = Palette.jet(256);           // cold-to-hot rainbow
Color[] rainbow = Palette.rainbow(256);       // full-spectrum
Color[] heat    = Palette.heat(256);          // black-red-yellow-white
Color[] terrain = Palette.terrain(256);       // green-yellow-brown-white
Color[] topo    = Palette.topo(256);          // blue-cyan-green-yellow-red
Color[] gray    = Palette.grayscale(256);     // monochrome

double[][] points = {{1, 2}, {3, 4}, {5, 6}};

// Simplest form — black circles
ScatterPlot.of(points).figure().show();

// Custom mark and color
ScatterPlot.of(points, '@', Color.RED).figure().show();

// Multiple groups with automatic color assignment
double[][] x = ...;  // n-by-2
String[] labels = {"setosa", "versicolor", "virginica"};
ScatterPlot.of(x, labels, '*').figure().show();

// Integer class labels
int[] y = ...;
ScatterPlot.of(x, y, 'o').figure().show();

// 3-D scatter (n-by-3 points)
double[][] xyz = ...;
ScatterPlot.of(xyz, '@', Color.BLUE).figure().show();

DataFrame iris = Read.arff(Paths.getTestData("weka/iris.arff"));

// 2-D: two numeric columns
ScatterPlot.of(iris, "sepallength", "sepalwidth", '*', Color.BLUE)
           .figure().setAxisLabels("Sepal Length", "Sepal Width")
           .show();

// 2-D with category coloring
ScatterPlot.of(iris, "sepallength", "sepalwidth", "class", '*')
           .figure().show();

// 3-D
ScatterPlot.of(iris, "sepallength", "sepalwidth", "petallength", "class", '*')
           .figure().show();

double[] y = {0, 1, 4, 9, 16, 25};      // x = 0, 1, 2, 3, 4, 5

// y values only — x-coordinates default to [0, n)
LinePlot.of(y, Color.BLUE).figure().show();

// Explicit (x, y) pairs
double[][] xy = {{0,0},{1,1},{2,4},{3,9}};
LinePlot.of(xy, Line.Style.DASH, Color.RED).figure().show();

// With legend
LinePlot.of(y, Line.Style.SOLID, Color.GREEN, "y = x²")
        .figure().show();

// Parametric curve (heart)
double[][] heart = new double[200][2];
for (int i = 0; i < 200; i++) {
    double t = Math.PI * (i - 100) / 100.0;
    heart[i][0] = 16 * Math.pow(Math.sin(t), 3);
    heart[i][1] = 13 * Math.cos(t) - 5 * Math.cos(2*t)
                - 2 * Math.cos(3*t) - Math.cos(4*t);
}
LinePlot.of(heart, Color.RED).figure().show();

Figure fig = LinePlot.of(sin, Line.Style.SOLID, Color.BLUE, "sin").figure();
fig.add(LinePlot.of(cos, Line.Style.DASH,  Color.RED,  "cos"));
fig.show();

// Simple bar chart (values at positions 0, 1, 2, …)
double[] heights = {3.2, 5.1, 2.8, 4.4};
BarPlot.of(heights).figure().show();

// Integer data
int[] counts = {10, 25, 18, 30};
BarPlot.of(counts).figure().show();

// Multiple groups (grouped bar chart)
double[][] grouped = {
    {1.0, 2.0, 3.0},   // group A
    {1.5, 2.5, 1.8}    // group B
};
BarPlot.of(grouped, new String[]{"Group A", "Group B"}).figure().show();

double[] setosa     = ...;   // petal lengths for each species
double[] versicolor = ...;
double[] virginica  = ...;

BoxPlot bp = new BoxPlot(
    new double[][]{setosa, versicolor, virginica},
    new String[]{"setosa", "versicolor", "virginica"}
);
bp.figure().setAxisLabels("", "Petal Length").show();

// Without labels
BoxPlot.of(setosa, versicolor, virginica).figure().show();

double[] data = ...;   // raw sample

// Default bins (square-root rule), probability density
Histogram.of(data).figure().show();

// Explicit bin count, frequency scale
Histogram.of(data, 30, false).figure().show();

// Custom color
Histogram.of(data, 20, true, Color.ORANGE).figure().show();

// Custom breakpoints (minimum 2 bins required)
double[] breaks = {0, 10, 20, 30, 40, 50};
Histogram.of(data, breaks, true).figure().show();

double[] sample = ...;

// One-sample: compare to standard normal
QQPlot.of(sample).figure().show();

// One-sample: compare to any Distribution
QQPlot.of(sample, new ExponentialDistribution(1.0)).figure().show();

// Two-sample
QQPlot.of(sampleA, sampleB).figure().show();

// Integer data
int[] counts = ...;
QQPlot.of(counts, new PoissonDistribution(3.0)).figure().show();

double[][] z = ...;    // m × n matrix of values

// Simplest — 16-color jet palette
Heatmap.of(z).figure().show();

// Custom palette size
Heatmap.of(z, 256).figure().show();

// Custom palette
Heatmap.of(z, Palette.heat(256)).figure().show();

// With axis coordinates
double[] x = IntStream.range(0, n).asDoubleStream().toArray();
double[] y = IntStream.range(0, m).asDoubleStream().toArray();
Heatmap.of(x, y, z, 64).figure().show();

// With string row/column labels (e.g. correlation matrix)
String[] genes = {"BRCA1", "TP53", "EGFR"};
Heatmap.of(genes, genes, correlation, 16).figure().show();

double[][] z = ...;

// Standalone contour (10 levels, linear)
Contour.of(z).figure().show();

// Overlay on a heatmap
Figure fig = Heatmap.of(z, 256).figure();
fig.add(Contour.of(z));
fig.show();

// Custom number of levels
Contour.of(z, 20, false).figure().show();      // 20 linear levels
Contour.of(z, 10, true).figure().show();       // 10 log-scale levels

// With explicit x/y coordinates
Contour.of(x, y, z).figure().show();

// Explicit contour levels (values at which to draw isolines)
double[] levels = {0.1, 0.5, 1.0, 2.0};
new Contour(z, levels).figure().show();

double[][] z = ...;   // m × n grid

// Regular grid (x, y auto-assigned to 0.5, 1.5, 2.5, …)
Surface.of(z).figure().show();

// With color palette
Surface.of(z, Palette.jet(256, 1.0f)).figure().show();

// Explicit x/y coordinates
double[] x = ...;
double[] y = ...;
Surface.of(x, y, z, Palette.heat(128)).figure().show();

// Irregular mesh (m × n × 3 data)
double[][][] mesh = ...;   // mesh[i][j] = {xi, yj, zij}
new Surface(mesh, Palette.jet(256)).figure().show();

// varianceProportion[i] = fraction of total variance in PC i+1
double[] varianceProportion = pca.varianceProportion();
new ScreePlot(varianceProportion).figure().show();

SparseMatrix A = SparseMatrix.text(path);

// Structure only (black dots)
SparseMatrixPlot.of(A).figure().setTitle("Sparsity pattern").show();

// Values as colors
SparseMatrixPlot.of(A, Palette.jet(256)).figure().show();

// merge  : (n-1) × 2 merge matrix from HierarchicalClustering
// height : (n-1) non-decreasing merge heights
int[][] merge  = hclust.tree();
double[] height = hclust.height();

new Dendrogram(merge, height).figure().show();

// Custom color
new Dendrogram(merge, height, Color.DARK_GRAY).figure().show();

// points[i] is the coordinate; texts[i] is the label
double[][] coords = ...;
String[] texts    = ...;
TextPlot.of(coords, texts).figure().show();

// Custom color
TextPlot.of(coords, texts, Color.BLUE).figure().show();

// Overlay text annotations on an existing scatter plot
Figure fig = ScatterPlot.of(coords, '.').figure();
fig.add(TextPlot.of(coords, texts));
fig.show();

double[][] steps = {{0,0},{1,1},{2,1},{3,2},{4,2},{5,3}};
StaircasePlot.of(steps).figure().show();

// Custom color
StaircasePlot.of(steps, Color.GREEN).figure().show();

MultiFigurePane panel = new MultiFigurePane(2, 3);   // 2 rows, 3 columns
panel.add(new Canvas(fig1));
panel.add(new Canvas(fig2));
// ...
panel.window().setVisible(true);

// Uniform color
MultiFigurePane.splom(iris, '.', Color.BLUE).window();

// Category-colored
MultiFigurePane.splom(iris, '*', "class").window();

Figure fig = plot.figure();

// Axis labels (shorthand for setting all at once)
fig.setAxisLabels("Sepal Length (cm)", "Sepal Width (cm)");

// Set a single axis label
fig.setAxisLabel(0, "Component 1");

// Custom tick marks
double[] positions = {0.5, 1.5, 2.5, 3.5};
String[] tickLabels = {"A", "B", "C", "D"};
fig.getAxis(0).setTicks(tickLabels, positions);

// Rotate axis labels (in radians; useful when labels are long)
fig.getAxis(0).setRotation(-Math.PI / 2);   // -90°

// Toggle grid lines
fig.getAxis(0).setGridVisible(false);
fig.getAxis(1).setGridVisible(true);

// Toggle tick marks and frame border
fig.getAxis(0).setTickVisible(false);
fig.getAxis(0).setFrameVisible(false);

// Show / hide all legends
fig.setLegendVisible(false);

// Per-plot: supply Legend[] when constructing a plot
Legend[] legends = {
    new Legend("Class A", Color.RED),
    new Legend("Class B", Color.BLUE)
};
new ScatterPlot(points, legends).figure().show();

Figure fig = Heatmap.of(z, Palette.jet(256)).figure();
fig.setTitle("Z-scores");

// Export to PNG
BufferedImage img = fig.toBufferedImage(1920, 1080);
ImageIO.write(img, "png", Path.of("heatmap.png").toFile());

// Convert to byte array (for REST endpoints, etc.)
ByteArrayOutputStream baos = new ByteArrayOutputStream();
ImageIO.write(img, "png", baos);
byte[] pngBytes = baos.toByteArray();

Canvas canvas = new Canvas(figure);
Headless h = new Headless(canvas, 800, 600);
h.show();
// canvas is now laid-out and can be painted off-screen

┌────────────────────────────────────────────────────────────────┐
│  User code                                                     │
│  ScatterPlot.of(…) ──► Figure ──► FigurePane ──► JFrame       │
└───────────────────┬───────────────────────────────────────────┘
                    │
        ┌───────────▼────────────┐
        │  Figure                │
        │  ├─ Base (coord space) │
        │  ├─ Axis[]             │
        │  └─ List<Shape>        │
        │       ├─ Plot          │◄── ScatterPlot, LinePlot, …
        │       │    └─ Point[]  │
        │       ├─ Label         │
        │       └─ GridLabel     │
        └───────────┬────────────┘
                    │ paint(Renderer)
        ┌───────────▼────────────┐
        │  Canvas (JComponent)   │
        │  └─ Renderer           │
        │       └─ Projection2D  │
        │           or           │
        │          Projection3D  │
        └────────────────────────┘