Package edu.cnu.mdi.mdi3D.item3D

Class ScatterPlot3D

java.lang.Object
edu.cnu.mdi.mdi3D.item3D.Item3D
edu.cnu.mdi.mdi3D.item3D.ScatterPlot3D
public class ScatterPlot3D extends Item3D
A thread-safe 3D scatter plot for use on a Panel3D.

Overview

ScatterPlot3D renders a collection of colored spheres as a scatter plot inside a dynamic wireframe bounding box. The bounding box starts at a caller-supplied initial size and grows automatically as new data points are added.

Threading

add(float, float, float, float) and add(float, float, float, Color) are safe to call from any thread, including high-frequency producer threads. Each call atomically expands the bounding-box bounds and enqueues the new sphere. A repaint is then requested on the EDT via a coalescing gate: no matter how many add() calls arrive between two EDT ticks, at most one repaint() is scheduled. This prevents EDT flooding during a data storm while ensuring the display stays live.

Throttling

An optional minimum repaint interval (setThrottleMs(long), default 50 ms ≈ 20 fps) further limits refresh rate under extreme load. Set to 0 to repaint as fast as the EDT can process.

Color Mapping

Use add(float, float, float, float) with a scalar value in [0, 1] to get automatic scientific coloring. The default map is ScientificColorMap.VIRIDIS, but any MDI scientific color map can be selected with setColorMap(ScientificColorMap). You can also supply an explicit Color via add(float, float, float, Color).

Usage


 // Create the plot and add it to the panel
 ScatterPlot3D scatter = new ScatterPlot3D(panel,
         -1f, 1f,   // X range
         -1f, 1f,   // Y range
         -1f, 1f);  // Z range
 panel.addItem(scatter);
 panel.softRefresh();

 // From any thread — safe during a data storm
 scatter.add(x, y, z, normalizedValue);   // 0..1 → heat-map color
 scatter.add(x, y, z, Color.CYAN);        // explicit color

 // Tune the refresh rate
 scatter.setThrottleMs(16);   // ~60 fps cap
 scatter.setPointRadius(0.02f);

  • Constructor Details

    • ScatterPlot3D

      public ScatterPlot3D(Panel3D panel3D, float minX, float maxX, float minY, float maxY, float minZ, float maxZ)
      Create a scatter plot with an explicit initial bounding box. The box will grow automatically as points outside it are added.
      Parameters:
      panel3D - the owner Panel3D
      minX - initial minimum X bound
      maxX - initial maximum X bound
      minY - initial minimum Y bound
      maxY - initial maximum Y bound
      minZ - initial minimum Z bound
      maxZ - initial maximum Z bound

    • ScatterPlot3D

      public ScatterPlot3D(Panel3D panel3D, float halfExtent)
      Create a scatter plot with a symmetric cubic initial bounding box centred at the origin.
      Parameters:
      panel3D - the owner Panel3D
      halfExtent - half-length of each side (box runs from -halfExtent to +halfExtent on every axis)

  • Method Details

    • add

      public void add(float x, float y, float z, float value)
      Add a data point using a scalar value mapped through the current ScientificColorMap.
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      value - scalar in [0, 1]; values outside the range are clamped

    • add

      public void add(float x, float y, float z, Color color)
      Add a data point with an explicit color.
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      color - the sphere color

    • clear

      public void clear(float minX, float maxX, float minY, float maxY, float minZ, float maxZ)
      Remove all data points and reset the bounding box to its initial size. Safe to call from any thread.
      Parameters:
      minX - new bounding-box minimum x
      maxX - new bounding-box maximum x
      minY - new bounding-box minimum y
      maxY - new bounding-box maximum y
      minZ - new bounding-box minimum z
      maxZ - new bounding-box maximum z

    • setThrottleMs

      public void setThrottleMs(long ms)
      Set the minimum interval between scheduled repaints. Use 0 to remove the throttle entirely.
      Parameters:
      ms - milliseconds (≥ 0)

    • setPointRadius

      public void setPointRadius(float radius)
      Set the radius of each data-point sphere. Default is 0.025.
      Parameters:
      radius - sphere radius, in world units

    • setResolution

      public void setResolution(int slices, int stacks)
      Set the sphere tessellation resolution. Higher values produce smoother spheres at the cost of render time.
      Parameters:
      slices - longitude divisions (min 3)
      stacks - latitude divisions (min 2)

    • setBoxColor

      public void setBoxColor(Color color)
      Set the wireframe bounding-box color.
      Parameters:
      color - the box color

    • setShowBox

      public void setShowBox(boolean show)
      Show or hide the wireframe bounding box.
      Parameters:
      show - true to draw the box

    • setColorMap

      public void setColorMap(edu.cnu.mdi.ui.colors.ScientificColorMap colorMap)
      Select the scientific color map used by add(float, float, float, float). Passing null restores ScientificColorMap.VIRIDIS.
      Parameters:
      colorMap - the map to use, or null for Viridis

    • setRenderStyle

      public void setRenderStyle(ScatterPlot3D.RenderStyle renderStyle)
      Select how scatter markers are rendered. ScatterPlot3D.RenderStyle.AUTO is the default and switches from spheres to fast OpenGL points for large data sets.
      Parameters:
      renderStyle - the render style, or null for AUTO

    • setPointSize

      public void setPointSize(float pointSize)
      Set the OpenGL point size used by ScatterPlot3D.RenderStyle.POINTS.
      Parameters:
      pointSize - point size, in pixels (clamped to at least 1)

    • setAutoPointThreshold

      public void setAutoPointThreshold(int threshold)
      Set the AUTO-mode point/sphere switch threshold.
      Parameters:
      threshold - point count above which ScatterPlot3D.RenderStyle.AUTO switches from spheres to points (clamped to at least 1)

    • setShowFloorGrid

      public void setShowFloorGrid(boolean showFloorGrid)
      Show or hide the light floor grid drawn on the lower Z plane.
      Parameters:
      showFloorGrid - true to draw the floor grid

    • setGridColor

      public void setGridColor(Color gridColor)
      Set the floor-grid color.
      Parameters:
      gridColor - the grid color, or null to restore the default

    • setGridDivisions

      public void setGridDivisions(int gridDivisions)
      Set the number of floor-grid divisions in X and Y.
      Parameters:
      gridDivisions - number of divisions per axis (clamped to at least 1)

    • setAxisLabels

      public void setAxisLabels(String xLabel, String yLabel, String zLabel)
      Set the axis titles drawn by this scatter plot.

      Axis text is rendered as a screen-space overlay using TextRendering3D, so it remains crisp and readable as the plot is rotated or zoomed. Passing null for a label makes that title blank.

      Parameters:
      xLabel - x-axis title
      yLabel - y-axis title
      zLabel - z-axis title

    • setShowAxisText

      public void setShowAxisText(boolean showAxisText)
      Show or hide the scatter plot's built-in axis titles and tick labels.
      Parameters:
      showAxisText - true to draw axis text

    • setAxisTickCount

      public void setAxisTickCount(int axisTickCount)
      Set the number of major tick intervals per axis. A value of 4 draws five labels, including both end points.
      Parameters:
      axisTickCount - number of intervals; values less than zero are treated as zero

    • setBoundsListener

      public void setBoundsListener(ScatterPlot3D.BoundsListener listener)
      Register a listener that is called on the EDT whenever the bounding box expands. The float array passed to the listener is [minX, maxX, minY, maxY, minZ, maxZ].

      Multiple expansions that arrive between EDT ticks are coalesced into a single callback carrying the latest bounds at that moment. Pass null to remove the listener.

      Parameters:
      listener - the bounds listener, or null

    • getPointCount

      public int getPointCount()
      Return the current committed point count.

    • getTotalPointCount

      public int getTotalPointCount()
      Return the committed plus pending point count.

    • getBoundsSnapshot

      public float[] getBoundsSnapshot()
      Return a bounds snapshot as [minX, maxX, minY, maxY, minZ, maxZ].

    • dispose

      protected void dispose(com.jogamp.opengl.GLAutoDrawable drawable)
      Releases the lazily-created axis-title and tick-label TextRendering3D renderers, which each own a GPU texture atlas via their underlying JOGL TextRenderer.
      Overrides:
      dispose in class Item3D
      Parameters:
      drawable - the OpenGL drawable being disposed

    • draw

      public void draw(com.jogamp.opengl.GLAutoDrawable drawable)
      Description copied from class: Item3D
      The custom drawing method
      Specified by:
      draw in class Item3D
      Parameters:
      drawable - the OpenGL drawable

    • getSortPoint

      public float[] getSortPoint()
      Description copied from class: Item3D
      A representative point for transparent sorting, in world coordinates. Default is origin. Override in items with a natural center (Sphere, Cube, Cylinder, etc.).
      Overrides:
      getSortPoint in class Item3D
      Returns:
      the sort point as [x, y, z]

    • heatMapColor

      public static Color heatMapColor(float t)
      Legacy convenience method. New code should normally use ScientificColorMap. Maps a scalar value in [0, 1] to a five-stop heat-map color: blue (0) → cyan (0.25) → green (0.5) → yellow (0.75) → red (1).
      Parameters:
      t - value in [0, 1] (clamped)
      Returns:
      interpolated AWT Color