jRenderer3D
Class JRenderer3D

java.lang.Object
  jRenderer3D.JRenderer3D

public class JRenderer3D
extends java.lang.Object

The framework JRenderer3D provides the possibility to implement easily a 3D display to ImageJ plugins.

This is the basic scheme for rendering 3D scenes.
After initializing a new 3D scene, objects are added, drawing parameters and global render parameters have to be set.
At the end a rendering is performed that is writen to an image, which can be displayed with ImageJ.

Example:

Setup 3D rendering
JRenderer3D jRenderer3D;
jRenderer3D = new JRenderer3D(xCenter, yCenter, zCenter); // size of the rendered image

Set or add one or more 3D objects like points or spheres:
jRenderer3D.addPoint3D(250, 250, 20, 20, Color.WHITE);

Or lines, texts, cubes:
jRenderer3D.add3DCube(0, 0, 0, xSize, ySize, zSize, 0xFF000000);

Set one image for a surface plot
jRenderer3D.setSurfacePlot(imp);

Or set a volume (a 3D-stack)
jRenderer3D.setVolume(imagePlus); // set the volume

Set the drawing modes
jRenderer3D.setPoints3DDrawMode(JRenderer3D.POINTS_SPHERES);
jRenderer3D.setSurfacePlotLut(JRenderer3D.LUT_ORANGE); // select a LUT
jRenderer3D.setSurfacePlotLight(0.5); // set lighting
jRenderer3D.setSurfacePlotMode(JRenderer3D.SURFACEPLOT_MESH); // set plot mode to mesh

Set global parameters
jRenderer3D.setBackgroundColor(0xFF000050); // dark blue background
jRenderer3D.setZAspect(4); // set the z-aspect ratio to 4
jRenderer3D.setTransformScale(1.5); // scale factor
jRenderer3D.setTransformRotationXYZ(80, 0, 160); // rotation angles (in degrees)

Render the image
jRenderer3D.doRendering();

Get the rendered new image
Image image = jRenderer3D.getImage();

And display it
ImagePlus impNew = new ImagePlus("Rendered Image", image);
impNew.show();
impNew.updateAndDraw();

Possible 3D elements to draw:

• Point3D
• Line3D
• Text3D
• Surface:
  

  Surface plots can be generate from all image types. Selections, which can be non-rectangular, are supported.

  The luminance of an image is interpreted as height for the plot. Internally the image is scaled to a 256x256 image using nearest neighbor sampling. Other dimensions for this image can be set by the setSurfacePlotGridSize method.

  The surface plot has several drawing modes which av be set by setSurfacePlotMode:

  • Dots: All pixels are drawn as small dots.
  • Lines: All pixels are connected in the x-direction.
  • Mesh: All pixels are connected in the x- and y-direction.
  • Filled: All pixels are connected without leaving holes

  Display Colors can be chosen from the original color, grayscale, different LUTs and orange.

  Noisy images can be smoothed using the applySurfaceSmoothingFilter method. Setting lighting with the setSurfacePlotLight methode gives the impression that the plot was illuminated and so improves the visibility of small differences.

• Volume

  Stacks can be shown as volumes or slices. 8, 16 and 32 bit stacks are supported. RGB-stacks are not supported for the moment.

  The display mode of a volume may be set with the setVolumeDrawMode method by using these constants:

  • VOLUME_SLICE_NEARESTNEIGHBOR: A slice through the volume. No interpolation is performed.
  • VOLUME_SLICE_TRILINEAR: A slice through the volume using trilinear interpolation.
  • VOLUME_DOTS: Voxels are shown according to their distance, no interpolation is performed.
  • VOLUME_PROJECTION_TRILINEAR_BACK: A 3D volume is rendered. The opacity of the voxels is controlled by the setVolumeThreshold method. Values below the threshold are interpreted as transparent.

  The setVolumeCutDistance method sets the distance of the slice. For volume rendering only voxels further away than this distance are displayed. The z-aspect ratio of a volume is read automatically, but it can also be set using the setTransformZAspectRatio.

  Different LUTs can be used for display by using the setVolumeLut method.

Before rendering a scene a geometrical transform is applied. Rotation angles for the x, y, and z-coordinate achses may be set by the setTransformRotation* methods. the global scale is set by the setTransformScale method. JRederer3D assumes the following coordinate system:

The z-axis is pointing towards the viewer. The orientation of the z-axis may be changed with the method setTransformZOrientation. The entire scene is centered to the center coordinates that are passed with the constructor of JRenderer3D.

The 3D scene is rendered to an image buffer. The initial size of this buffer is 512x512 pixels: This size can be changed with the setBufferSize method.

Version:

1.0

Author:

Kai Uwe Barthel

Field Summary

static int	LUT_BLACK 3D representations of objects are drawn in black.
static int	LUT_BLUE 3D representations of objects are drawn in blue.
static int	LUT_FIRE 3D representations of objects are drawn with fire colors.
static int	LUT_GRAY 3D representations of objects are drawn with grayscale colors.
static int	LUT_ORANGE 3D representations of objects are drawn in orange.
static int	LUT_ORIGINAL 3D represenations of objects are drawn with their original colors.
static int	LUT_SPECTRUM 3D representations of objects are drawn with spectrum colors.
static int	LUT_THERMAL 3D representations of objects are drawn with thermal colors.
static int	POINT_CIRCLE Draws a point as a (2D) circle.
static int	POINT_DOT Draws a point as a dot.
static int	POINT_SPHERE Draws a point as a sphere (slowest).
static int	SURFACEPLOT_DOTS Draws a surface plot using only dots, illumination is active.
static int	SURFACEPLOT_DOTSNOLIGHT Draws a surface plot using only dots, no illumination is used (fastest mode).
static int	SURFACEPLOT_FILLED Draws a filled surface plot (Slowest mode).
static int	SURFACEPLOT_LINES Draws a surface plot using lines.
static int	SURFACEPLOT_MESH Draws a surface plot using a mesh.
static int	VOLUME_DOTS Draws a volume using only dots (fastest mode).
static int	VOLUME_PROJECTION_TRILINEAR_FRONT Draws a volume using trilinear interpolation projection from the front
static int	VOLUME_SLICE_NEAREST_NEIGHBOR Draws a volume using nearest neighbor interpolation.
static int	VOLUME_SLICE_TRILINEAR Draws a volume using trilinear interpolation.

Constructor Summary

JRenderer3D()
Creates a new JRenderer3D object.

JRenderer3D(int xCenter, int yCenter, int zCenter)
Creates a new JRenderer3D object.

Method Summary

void	add3DCube(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, java.awt.Color color) Adds a cube (drawn with 12 lines) to the 3D scene.
void	add3DCube(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, int rgb) Adds a cube (drawn with 12 lines) to the 3D scene.
void	addLine3D(int xStart, int yStart, int zStart, int xEnd, int yEnd, int zEnd, java.awt.Color color) Adds a single 3D line to the 3D scene.
void	addLine3D(Line3D line3D) Adds a single 3D line to the 3D scene.
void	addLines3D(Line3D[] lines3D) Adds an array of lines to the 3D scene.
void	addPoint3D(int x, int y, int z, int size, java.awt.Color color, int drawMode) Adds a point to the 3D scene.
void	addPoint3D(int x, int y, int z, int size, int rgb, int drawMode) Adds a point to the 3D scene.
void	addPoint3D(Point3D point3D) Adds a single Point3D to the 3D scene.
void	addPoints3D(Point3D[] points3D) Adds an array with Point3D to the 3D scene.
void	addText3D(java.lang.String text, int x, int y, int z, java.awt.Color color, int size) Adds a text to the 3D scene.
void	addText3D(Text3D text3D) Adds a single 3D text to the 3D scene.
void	addText3D(Text3D[] text3D) Adds an array of text to the 3D scene.
void	applySurfaceSmoothingFilter(int smoothRadius) Aplies a smoothing to the surface plot data
void	changeTransformRotationXYZ(double changeX, double changeY, double changeZ) Changes the rotation of x-, y-, and z-axis by the values of changeX and changeY.
void	changeTransformRotationXZ(double changeX, double changeZ) Changes the rotation of x- and z-axis by the values of changeX and changeY.
void	doRendering() This methods does the rendering and creates the 3D output.
int	getHeight() Returns the buffer height of the image.
java.awt.Image	getImage() Returns actual rendered image.
double	getTransformZAspectRatio() Gets the z-aspect ratio (the relative z-height of a voxel).
int	getWidth() Returns the buffer width of the image.
void	setBackgroundColor(java.awt.Color color) Sets the background color of the rendered 3D presentation
void	setBackgroundColor(int rgb) Sets the background color of the rendered 3D presenation
void	setBufferSize(int width, int height) Sets the buffer size.
void	setSurfacePlot(ij.ImagePlus imp) Creates the surface plot.
void	setSurfacePlotGridSize(int width, int height) Sets the surface grid size (sampling rate).
void	setSurfacePlotLight(double surfacePlot_light) Sets the lightning for the surface plot illumination .
void	setSurfacePlotLut(int surfacePlot_lutNr) Sets the color lut for the surface plot.
void	setSurfacePlotMode(int surfacePlot_plotMode) Sets the surface plot mode.
void	setSurfacePlotWithTexture(ij.ImagePlus imp, ij.ImagePlus impTexture) Creates the surface plot with texture.
void	setTransformRotationX(double ax) Sets the rotation on the x-axis.
void	setTransformRotationXYZ(double ax, double ay, double az) Sets the rotation on x-, y- and z-axis.
void	setTransformRotationXZ(double ax, double az) Sets the rotation on both x- and z-axis.
void	setTransformRotationY(double ay) Sets the rotation on the y-axis.
void	setTransformRotationZ(double az) Sets the rotation on the z-axis.
void	setTransformScale(double scale) Sets scale of the redered 3D scene.
void	setTransformZAspectRatio(double zAspectRatio) Sets the z-aspect ratio (the relative z-height of a voxel).
void	setTransformZOrientation(int zOrientation) Chooses the coordinate system.
void	setVolume(ij.ImagePlus imagePlus) Sets a volume stack.
void	setVolumeCutDistance(int volume_cutDist) Sets the view distance.
void	setVolumeDotsSubsampling(int volume_dotsDeltaX, int volume_dotsDeltaY, int volume_dotsDeltaZ) Set subsampling factors (used by the drawing mode volume dots).
void	setVolumeDrawMode(int volume_drawMode) Sets the mode for drawing volumes.
void	setVolumeLut(int volume_lutNr)
void	setVolumeThreshold(int threshold) Sets the threshold.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POINT_SPHERE

public static final int POINT_SPHERE

Draws a point as a sphere (slowest).

See Also:

Constant Field Values

POINT_CIRCLE

public static final int POINT_CIRCLE

Draws a point as a (2D) circle.

See Also:

Constant Field Values

POINT_DOT

public static final int POINT_DOT

Draws a point as a dot. Size information has no effect.

See Also:

Constant Field Values

SURFACEPLOT_DOTSNOLIGHT

public static final int SURFACEPLOT_DOTSNOLIGHT

Draws a surface plot using only dots, no illumination is used (fastest mode).

See Also:

Constant Field Values

SURFACEPLOT_DOTS

public static final int SURFACEPLOT_DOTS

Draws a surface plot using only dots, illumination is active.

See Also:

Constant Field Values

SURFACEPLOT_LINES

public static final int SURFACEPLOT_LINES

Draws a surface plot using lines. Number of lines can be adjusted.

See Also:

Constant Field Values

SURFACEPLOT_MESH

public static final int SURFACEPLOT_MESH

Draws a surface plot using a mesh. Mesh size can be adapted.

See Also:

Constant Field Values

SURFACEPLOT_FILLED

public static final int SURFACEPLOT_FILLED

Draws a filled surface plot (Slowest mode).

See Also:

Constant Field Values

VOLUME_DOTS

public static final int VOLUME_DOTS

Draws a volume using only dots (fastest mode).

See Also:

Constant Field Values

VOLUME_SLICE_NEAREST_NEIGHBOR

public static final int VOLUME_SLICE_NEAREST_NEIGHBOR

Draws a volume using nearest neighbor interpolation.

See Also:

Constant Field Values

VOLUME_SLICE_TRILINEAR

public static final int VOLUME_SLICE_TRILINEAR

Draws a volume using trilinear interpolation.

See Also:

Constant Field Values

VOLUME_PROJECTION_TRILINEAR_FRONT

public static final int VOLUME_PROJECTION_TRILINEAR_FRONT

Draws a volume using trilinear interpolation projection from the front

See Also:

Constant Field Values

LUT_ORIGINAL

public static final int LUT_ORIGINAL

3D represenations of objects are drawn with their original colors.

See Also:

Constant Field Values

LUT_GRAY

public static final int LUT_GRAY

3D representations of objects are drawn with grayscale colors.

See Also:

Constant Field Values

LUT_SPECTRUM

public static final int LUT_SPECTRUM

3D representations of objects are drawn with spectrum colors.

See Also:

Constant Field Values

LUT_FIRE

public static final int LUT_FIRE

3D representations of objects are drawn with fire colors.

See Also:

Constant Field Values

LUT_THERMAL

public static final int LUT_THERMAL

3D representations of objects are drawn with thermal colors.

See Also:

Constant Field Values

LUT_ORANGE

public static final int LUT_ORANGE

3D representations of objects are drawn in orange.

See Also:

Constant Field Values

LUT_BLUE

public static final int LUT_BLUE

3D representations of objects are drawn in blue.

See Also:

Constant Field Values

LUT_BLACK

public static final int LUT_BLACK

3D representations of objects are drawn in black.

See Also:

Constant Field Values

Constructor Detail

JRenderer3D

public JRenderer3D()

Creates a new JRenderer3D object. This has always to be the first step to generate a 3D scene. The center is assumed at (0,0,0)

JRenderer3D

public JRenderer3D(int xCenter,
                   int yCenter,
                   int zCenter)

Creates a new JRenderer3D object.

This has always to be the first step to generate a 3D scene.

Parameters:

xCenter - The x-coordinate of the rotation / plot center.

yCenter - The y-coordinate of the rotation / plot center.

zCenter - The z-coordinate of the rotation / plot center.

Method Detail

doRendering

public void doRendering()

This methods does the rendering and creates the 3D output. It has to be redone after all setting changes (scale, angle, surface modes, lightning modes, color modes etc.) Draws all given input data (lines, text, points, cubes, surfaces).

addPoints3D

public void addPoints3D(Point3D[] points3D)

Adds an array with Point3D to the 3D scene.

Parameters:

points3D - array with points in a threedimensional coordinate system

addPoint3D

public void addPoint3D(Point3D point3D)

Adds a single Point3D to the 3D scene.

Parameters:

point3D - the 3D point to add

addPoint3D

public void addPoint3D(int x,
                       int y,
                       int z,
                       int size,
                       java.awt.Color color,
                       int drawMode)

Adds a point to the 3D scene.

Parameters:

x -

y -

z -

size -

color -

drawMode -

addPoint3D

public void addPoint3D(int x,
                       int y,
                       int z,
                       int size,
                       int rgb,
                       int drawMode)

Adds a point to the 3D scene.

Parameters:

x -

y -

z -

size -

rgb -

drawMode -

setSurfacePlot

public void setSurfacePlot(ij.ImagePlus imp)

Creates the surface plot.

Parameters:

imp - The images to be drawn in 3D.

setSurfacePlotWithTexture

public void setSurfacePlotWithTexture(ij.ImagePlus imp,
                                      ij.ImagePlus impTexture)

Creates the surface plot with texture.

Parameters:

imp - The images to be drawn in 3D.

impTexture - The image which shall be used as texture

setSurfacePlotMode

public void setSurfacePlotMode(int surfacePlot_plotMode)

Sets the surface plot mode.

Available options:

• PLOT_DOTSNOLIGHT: if used, no lightning options are applied (fastest)
• PLOT_DOTS: draws dots
• PLOT_LINES: draws lines
• PLOT_MESH: draws a mesh
• PLOT_FILLED: fills the 3d object completely (slowest)

Parameters:

surfacePlot_plotMode - the surface plot mode

setVolumeDrawMode

public void setVolumeDrawMode(int volume_drawMode)

Sets the mode for drawing volumes.

• VOLUME_DOTS: draws volumes with dots(fastest)

Parameters:

volume_drawMode -

setVolumeLut

public void setVolumeLut(int volume_lutNr)

setVolumeDotsSubsampling

public void setVolumeDotsSubsampling(int volume_dotsDeltaX,
                                     int volume_dotsDeltaY,
                                     int volume_dotsDeltaZ)

Set subsampling factors (used by the drawing mode volume dots). This allows faster drawing in the VOLUME_DOTS mode. (default values are 1)

Parameters:

volume_dotsDeltaX - subsampling factor in x direction

volume_dotsDeltaY -

volume_dotsDeltaZ -

setVolumeCutDistance

public void setVolumeCutDistance(int volume_cutDist)

Sets the view distance. Just the voxels behind the distance are drawn.

Parameters:

volume_cutDist - the cut distance

setSurfacePlotGridSize

public void setSurfacePlotGridSize(int width,
                                   int height)

Sets the surface grid size (sampling rate). Should be set to an integer fraction of the image of which the surface plot has to be generated.

Parameters:

width - the width of surface grid

height - the height of surface grid

setTransformZOrientation

public void setTransformZOrientation(int zOrientation)

Chooses the coordinate system.

Parameters:

zOrientation -
-1: left hand coordinate system
1: right hand coordinate system

setTransformScale

public void setTransformScale(double scale)

Sets scale of the redered 3D scene.

Parameters:

scale - scales the scene

setTransformRotationX

public void setTransformRotationX(double ax)

Sets the rotation on the x-axis.

Parameters:

ax - angle in degree

setTransformRotationY

public void setTransformRotationY(double ay)

Sets the rotation on the y-axis.

Parameters:

ay - angle in degree

setTransformRotationZ

public void setTransformRotationZ(double az)

Sets the rotation on the z-axis.

Parameters:

az - angle in degree

setTransformRotationXZ

public void setTransformRotationXZ(double ax,
                                   double az)

Sets the rotation on both x- and z-axis.

Parameters:

ax - angle of x-axis in degree

az - angle of z-axis in degree

setTransformRotationXYZ

public void setTransformRotationXYZ(double ax,
                                    double ay,
                                    double az)

Sets the rotation on x-, y- and z-axis.

Parameters:

ax - rotation angle of x-axis in degree

ay - rotation angle of y-axis in degree

az - rotation angle of z-axis in degree

changeTransformRotationXZ

public void changeTransformRotationXZ(double changeX,
                                      double changeZ)

Changes the rotation of x- and z-axis by the values of changeX and changeY.

Parameters:

changeX - change of rotation angle of x-axis in degree

changeZ - change of rotation angle of z-axis in degree

changeTransformRotationXYZ

public void changeTransformRotationXYZ(double changeX,
                                       double changeY,
                                       double changeZ)

Changes the rotation of x-, y-, and z-axis by the values of changeX and changeY.

Parameters:

changeX - change of rotation angle of x-axis in degree

changeY - change of rotation angle of y-axis in degree

changeZ - change of rotation angle of z-axis in degree

setBackgroundColor

public void setBackgroundColor(int rgb)

Sets the background color of the rendered 3D presenation

Parameters:

rgb - the background color (argb int)

setBackgroundColor

public void setBackgroundColor(java.awt.Color color)

Sets the background color of the rendered 3D presentation

Parameters:

color - Color

addLines3D

public void addLines3D(Line3D[] lines3D)

Adds an array of lines to the 3D scene.

Parameters:

lines3D - array of 3d lines

addLine3D

public void addLine3D(Line3D line3D)

Adds a single 3D line to the 3D scene.

Parameters:

line3D - the 3D line to add

addLine3D

public void addLine3D(int xStart,
                      int yStart,
                      int zStart,
                      int xEnd,
                      int yEnd,
                      int zEnd,
                      java.awt.Color color)

Adds a single 3D line to the 3D scene.

Parameters:

xStart -

yStart -

zStart -

xEnd -

yEnd -

zEnd -

color -

addText3D

public void addText3D(Text3D[] text3D)

Adds an array of text to the 3D scene.

Parameters:

text3D -

addText3D

public void addText3D(java.lang.String text,
                      int x,
                      int y,
                      int z,
                      java.awt.Color color,
                      int size)

Adds a text to the 3D scene.

Parameters:

text -

x -

y -

z -

color -

size -

addText3D

public void addText3D(Text3D text3D)

Adds a single 3D text to the 3D scene.

Parameters:

text3D - the 3D text to add

setBufferSize

public void setBufferSize(int width,
                          int height)

Sets the buffer size. (The size of the rendered 2D image)

Parameters:

width - The width to be set.

height - The height to be set.

add3DCube

public void add3DCube(int xMin,
                      int yMin,
                      int zMin,
                      int xMax,
                      int yMax,
                      int zMax,
                      java.awt.Color color)

Adds a cube (drawn with 12 lines) to the 3D scene.

Parameters:

xMin - minimum value x

yMin - minimum value y

zMin - minimum value z

xMax - maximum value x

yMax - maximum value y

zMax - maximum value z

color - Color of cube lines (argb)

add3DCube

public void add3DCube(int xMin,
                      int yMin,
                      int zMin,
                      int xMax,
                      int yMax,
                      int zMax,
                      int rgb)

Adds a cube (drawn with 12 lines) to the 3D scene.

Parameters:

xMin - minimum value x

yMin - minimum value y

zMin - minimum value z

xMax - maximum value x

yMax - maximum value y

zMax - maximum value z

rgb - Color of cube lines (argb)

setVolume

public void setVolume(ij.ImagePlus imagePlus)

Sets a volume stack.

Parameters:

imagePlus - the volume stack to be set

setSurfacePlotLut

public void setSurfacePlotLut(int surfacePlot_lutNr)

Sets the color lut for the surface plot.

• ORIGINAL
• GRAY
• SPECTRUM
• FIRE
• THERMAL
• ORANGE
• BLUE
• BLACK

Parameters:

surfacePlot_lutNr - color of look-up-table

setSurfacePlotLight

public void setSurfacePlotLight(double surfacePlot_light)

Sets the lightning for the surface plot illumination .

• 0: no light
• 1: strong light

Parameters:

surfacePlot_light - intensity value between 0 and 1 (default is 0)

applySurfaceSmoothingFilter

public void applySurfaceSmoothingFilter(int smoothRadius)

Aplies a smoothing to the surface plot data

Parameters:

smoothRadius - the radius of the smoothing kernel

setVolumeThreshold

public void setVolumeThreshold(int threshold)

Sets the threshold. All voxels below this threshold are displayed transparent.

Parameters:

threshold - Threshold to be set (0 .. 255).

setTransformZAspectRatio

public void setTransformZAspectRatio(double zAspectRatio)

Sets the z-aspect ratio (the relative z-height of a voxel). When setting a volume, the z-aspect ratio is reset to ratio read from the stack. If the z-aspect ratio needs to set this has to be done after calling the setVolume method.

Parameters:

zAspectRatio - z-aspect ratio (the relative z-ratio of a voxel) to be set.

getWidth

public int getWidth()

Returns the buffer width of the image.

Returns:

buffer width

getHeight

public int getHeight()

Returns the buffer height of the image.

Returns:

buffer height

getImage

public java.awt.Image getImage()

Returns actual rendered image.

Returns:

image

getTransformZAspectRatio

public double getTransformZAspectRatio()

Gets the z-aspect ratio (the relative z-height of a voxel).

Returns:

the z-aspect ratio