Jzy3d

Jzy3d is a framework for easily drawing 3d and 2d charts in Java, using either fast native GPU rendering or CPU based rendering to enhance portability across combination of OS/JVM/GPU.

The framework targets simplicity and portability across Java windowing toolkits (AWT, SWT, NEWT, Swing, JavaFX, Offscreen rendering), running either on MacOS, Windows and Linux. Jzy3d is available for other languages or platforms such as Scala, Groovy, Matlab, C#, and even Python.

The API can be used freely in commercial applications. You can explore the tutorials. an then purchase the extended developper guide to support the development effort.

How to use

Refer to the tutorial README file to get help on creating your first chart project with the help of example code.

As this library focuses on portability of the charts, the org.jzy3d.demos.surface package in jzy3d-tutorials demonstrates the same chart running on AWT, SWT, Swing using native OpenGL powered by JOGL and jGL CPU rendering.

public class SurfaceDemoAWT extends AWTAbstractAnalysis {
  public static void main(String[] args) throws Exception {
    SurfaceDemoAWT d = new SurfaceDemoAWT();
    AnalysisLauncher.open(d);
  }

  @Override
  public void init() {
    // Define a function to plot
    Mapper mapper = new Mapper() {
      @Override
      public double f(double x, double y) {
        return x * Math.sin(x * y);
      }
    };

    // Define range and precision for the function to plot
    Range range = new Range(-3, 3);
    int steps = 80;

    // Create the object to represent the function over the given range.
    final Shape surface = new SurfaceBuilder().orthonormal(new OrthonormalGrid(range, steps), mapper);
    surface.setColorMapper(new ColorMapper(new ColorMapRainbow(), surface, new Color(1, 1, 1, .5f)));
    surface.setFaceDisplayed(true);
    surface.setWireframeDisplayed(true);
    surface.setWireframeColor(Color.BLACK);

    // Create a chart
    GLCapabilities c = new GLCapabilities(GLProfile.get(GLProfile.GL2));
    IPainterFactory p = new AWTPainterFactory(c);
    IChartFactory f = new AWTChartFactory(p);

    chart = f.newChart(Quality.Advanced);
    chart.getScene().getGraph().add(surface);
  }
}

What's inside

Features

Multiple chart types

• Surface charts
• Scatter charts
• Volume charts
• Bar charts
• 3D and 2D graphs charts
• Many primitives to build custom charts (spheres, triangles, polygons, ...)

Flexible layout

• Colorbars
• Colormappers for coloring objects
• Axis box layout with detailed tick definition and tick rendering tools
• Contour functions
• Tooltips
• Background images
• 2D post renderers
• Lights

Algorithms

• Grid based and Delaunay surface tesselation methods
• 3d line strip interpolation to smooth pathes (Bernstein 3d)
• 2d envelopes (Convex hulls)
• Polygon ordering for improved transparency rendering
• Dual depth peeling: scene graph order independent transparency (expected for 1.0)
• Matlab-like array processors and statistics tools
• Experimental Support Vector Machine integration (Svm3d)

Interactions

• Mouse interaction with objects (selection & picking methods)
• Mouse interaction with chart (rotation, zoom, scale)
• Key interaction with chart (rotation, zoom, scale)
• Thread Controllers
• Animation of objects' structures (surface, series of lines, etc)

High and low level OpenGL programming

• Hide complexity and provide out of the box solutions for common low level OpenGL tasks
• Fully cutomizable framework with access to all OpenGL native features through JOGL

Cross platforms and compatible

• Straightforward integration to either AWT, Swing, Eclipse RCP (SWT), or JavaFX
• Windows, Unix, and MacOS. Android supposed to work if enable appropriate JOGL jars
• Offscreen rendering
• Multiple file formats (Ply, Obj, Matlab, CSV)
• C# port
• Python binding
• Scala example
• Matlab integration

Extensions

• jzy3d-graph : 3d graphs layout and rendering using Gephi toolkit
• jzy3d-spectro : 3d spectrogram
• jzy3d-bigpicture : drivers to few big data storage to draw massive amount of points

Dependent libraries

Jzy3d depends on the following libraries that are available on Jzy3d Maven repository (See tutorials for recommended Maven setup)

• jGL provides a pure Java implementation of OpenGL hence allowing CPU rendering as an alternative to GPU rendering (JOGL)
• jPLY supports the PLY format for loading 3d objects
• vecmath is a clone of a former java package

How to add to your project

The tutorial provides the code samples you need to add the library to a Maven project.

Download sources & javadocs in IDE

If you did not built the framework yourself and depend on Jzy3D Maven Repository, then you may wish to see sources and javadoc in your IDE. Simply call :

mvn dependency:resolve -Dclassifier=javadoc
mvn dependency:resolve -Dclassifier=sources

How to build

From command line

Build all

Run unit tests only

This will run all test named **/Test*.java or **/*Test.java.

mvn clean install

Run unit tests and automated integration tests

Integration tests compare charts to baseline images pixel wise. They are important in te toolbelt but have the drawback of being less portable accross computers

• Different OS have different frame insets (changing actual rendering area size) leading to chart screenshots of different size accross OS.
• Different OS have different frame insets (changing actual rendering area size) leading to chart a different layout (colorbar position)
• Different OS have different font rasterization (despite using the JVM font raterizer to minimize OS impact), hence text labels do not match despite having only a few pixel difference.
• A non HiDPI chart screenshot will not have the same size than the baseline that was generated on a Retina display (x2 pixel ratio). Integration tests that may be impacted by HiDPI are gathered in jzy3d-tests-java9 since at lest Java 9 JREs are required to detect HiDPI for EmulGL charts.

This will run all test named **/ITTest*.java and unit tests.

mvn clean install -Pintegration-tests

Skip automated tests

This will skip all tests (unit and integration)

mvn clean install -DskipTests

Manual tests

Some test require a manual verification.

Deploy source & javadocs

mvn clean source:jar javadoc:jar deploy

Generate javadoc site

Comment module jzy3d-tutorial manually

mvn compile javadoc:javadoc javadoc:aggregate

From intellij

Follow these steps to import in IntelliJ

• open an existing unrelated project
• file->new project from version control
• close the imported project window
• from the unrelated project ->file-> new project from existing sources -> select the new projects location
• from new project select top -> file -> add framework-> maven
• file -> set module language level

From eclipse

Import Maven project or Import Maven project from SCM

How to get help

• Google Discussion group
• Gitlab Discussions
• StackOverflow Tag
• If you are looking for professional services related to 3d rendering, contact me

Changes in 2.0 version

Version 2.0 is a major refactor to allow using multiple OpenGL implementations, which opened the door to EmulGL. To ease porting your 1.* charts, we add the following cheatsheet.

Renamings

Class name in 1.*	Class name in 2.0
Quality.Advanced, Intermediate	Quality.Advanced(), Intermediate()
AbstractDrawable	Drawable
AbstractWireframeable	Wireframeable
AxeBox	AxisBox
DrawableTexture	NativeDrawableImage & EmulGLDrawableImage
IChartComponentFactory	IChartFactory
AWTChartComponentFactory	AWTChartFactory
NewtChartComponentFactory	NewtChartFactory
JavaFXChartComponentFactory	❗ JavaFXChartFactory
SwingChartComponentFactory	SwingChartFactory
SWTChartComponentFactory	SWTChartFactory
	FallbackChartFactory
ColorbarViewportLayout	ViewAndColorbarsLayout
ViewMouseController	NewtViewCameraController
Halign	Horizontal
Valign	Vertical
Surface	SurfaceBuilder

❗ work in progress.

SurfaceBuilder is not static anymore to be overridable.

Additions

• IPainter
• IPainterFactory
• EmulGLPainterFactory
• IAnimator
• IImageWrapper and SymbolHandler

Deletions