gr3 Reference

General Functions

gr3.init(attrib_list=[])

Parameters:

attrib_list :

a list that can specify details about context creation. The attributes which use unsigned integer values are followed by these values.

Raise:

gr3.GR3_Error.GR3_ERROR_EXPORT: Raises GR3_Exception

GR3_ERROR_NONE	on success
GR3_ERROR_INVALID_VALUE	if one of the attributes’ values is out of the allowed range
GR3_ERROR_INVALID_ATTRIBUTE	if the list contained an unkown attribute or two mutually exclusive attributes were both used
GR3_ERROR_OPENGL_ERR	if an OpenGL error occured
GR3_ERROR_INIT_FAILED	if an error occured during initialization of the “window toolkit” (CGL, GLX, WIN…)

gr3.terminate()

This function terminates the gr3 context. After calling this function, gr3 is in the same state as when it was first loaded, except for context-independent variables, i.e. the logging callback.

Note

It is safe to call this function even if the context is not initialized.

See also

Functions gr.init()

gr3.getrenderpathstring()

This function allows the user to find out how his commands are rendered.

Returns:

If gr3 is initialized, a string in the format: “gr3 - ” + window toolkit + ” - ” + framebuffer extension + ” - ” + OpenGL version + ” - ” + OpenGL renderer string. For example “gr3 - GLX - GL_ARB_framebuffer_object - 2.1 Mesa 7.10.2 - Software Rasterizer” might be returned on a Linux system (using GLX) with an available GL_ARB_framebuffer_object implementation. If gr3 is not initialized “Not initialized” is returned.

gr3.geterrorstring(error_code)

Parameters:

error_code: The error code whose representation will be returned.

This function returns a string representation of a given error code.

gr3.setlogcallback(func)

Parameters:

‘func’: The logging callback, a function which gets a const char pointer as its only argument and returns nothing.

During software development it will often be helpful to get debug output from gr3. This information is not printed, but reported directly to the user by calling a logging callback. This function allows to set this callback or disable it again by calling it with NULL.

Scene Description Functions

gr3.clear()

This function clears the draw list.

Raises:

gr3.GR3_Error.GR3_ERROR_EXPORT: Raises GR3_Exception

GR3_ERROR_NONE	on success
GR3_ERROR_OPENGL_ERR	if an OpenGL error occured
GR3_ERROR_NOT_INITIALIZED	if the function was called without calling gr3_init() first

gr3.cameralookat(camera_x, camera_y, camera_z, center_x, center_y, center_z, up_x, up_y, up_z)

This function sets the view matrix by getting the position of the camera, the position of the center of focus and the direction which should point up. This function takes effect when the next image is created. Therefore if you want to take pictures of the same data from different perspectives, you can call and gr3.cameralookat(), gr3.getpixmap_(), gr3.cameralookat(), gr3.getpixmap_(), … without calling gr3_clear() and gr3_drawmesh() again.

Parameters:

camera_x : The x-coordinate of the camera

camera_y : The y-coordinate of the camera

camera_z : The z-coordinate of the camera

center_x : The x-coordinate of the center of focus

center_y : The y-coordinate of the center of focus

center_z : The z-coordinate of the center of focus

up_x : The x-component of the up direction

up_y : The y-component of the up direction

up_z : The z-component of the up direction

Note

Source: http://www.opengl.org/sdk/docs/man/xhtml/gluLookAt.xml

(as of 10/24/2011, licensed under SGI Free Software Licence B)

gr3.setcameraprojectionparameters(vertical_field_of_view, zNear, zFar)

This function sets the projection parameters. This function takes effect when the next image is created.

Parameters:

vertical_field_of_view : This parameter is the vertical field of view in degrees. It must be greater than 0 and less than 180.

zNear : The distance to the near clipping plane.

zFar : The distance to the far clipping plane.

Raises:

gr3.GR3_Error.GR3_ERROR_EXPORT: Raises GR3_Exception

GR3_ERROR_NONE	on success
GR3_ERROR_INVALID_VALUE	if one (or more) of the arguments is out of its range

Note

The ratio between zFar and zNear influences the precision of the depth buffer, the greater $ \frac{zFar}{zNear} $, the more likely are errors. So you should try to keep both values as close to each other as possible while making sure everything you want to be visible, is visible.

gr3.setlightdirection(*xyz)

This function sets the direction of light. If it is called with (0, 0, 0), the light is always pointing into the same direction as the camera.

Parameters:

x : The x-component of the light’s direction

y : The y-component of the light’s direction

z : The z-component of the light’s direction

gr3.setbackgroundcolor(red, green, blue, alpha)

This function sets the background color.

gr3.createmesh(n, vertices, normals, colors)

This function creates a int from vertex position, normal and color data. Returns a mesh.

Parameters:

vertices : the vertex positions

normals : the vertex normals

colors : the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn mesh

n : the number of vertices in the mesh

Raises:

gr3.GR3_Error.GR3_ERROR_EXPORT: Raises GR3_Exception

GR3_ERROR_NONE	on success
GR3_ERROR_OPENGL_ERR	if an OpenGL error occured
GR3_ERROR_OUT_OF_MEM	if a memory allocation failed

gr3.createindexedmesh(num_vertices, vertices, normals, colors, num_indices, indices)

This function creates an indexed mesh from vertex information (position, normal and color) and triangle information (indices). Returns a mesh.

Parameters:

num_vertices : the number of vertices in the mesh

vertices : the vertex positions

normals : the vertex normals

colors : the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn mesh

num_indices : the number of indices in the mesh (three times the number of triangles)

indices : the index array (vertex indices for each triangle)

Raises:

gr3.GR3_Error.GR3_ERROR_EXPORT: Raises GR3_Exception

GR3_ERROR_NONE	on success
GR3_ERROR_OPENGL_ERR	if an OpenGL error occured
GR3_ERROR_OUT_OF_MEM	if a memory allocation failed

gr3.createisosurfacemesh(grid, step=None, offset=None, isolevel=None)

This function creates an isosurface from voxel data using the marching cubes algorithm. Returns a mesh.

Parameters:

grid : 3D numpy array containing the voxel data

step : voxel sizes in each direction

offset : coordinate origin in each direction

isolevel : isovalue at which the surface will be created

Raises:

gr3.GR3_Error.GR3_ERROR_EXPORT: Raises GR3_Exception

GR3_ERROR_NONE	on success
GR3_ERROR_OPENGL_ERR	if an OpenGL error occured
GR3_ERROR_OUT_OF_MEM	if a memory allocation failed

gr3.drawmesh(mesh, n, positions, directions, ups, colors, scales)

This function adds a mesh to the draw list, so it will be drawn when the user calls gr3.getpixmap_(). The given data stays owned by the user, a copy will be saved in the draw list and the mesh reference counter will be increased.

Parameters:

mesh : The mesh to be drawn

positions : The positions where the meshes should be drawn

directions : The forward directions the meshes should be facing at

ups : The up directions

colors : The colors the meshes should be drawn in, it will be multiplied with each vertex color

scales : The scaling factors

n : The number of meshes to be drawn

gr3.deletemesh(mesh)

This function marks a mesh for deletion and removes the user’s reference from the mesh’s referenc counter, so a user must not use the mesh after calling this function. If the mesh is still in use for draw calls, the mesh will not be truly deleted until gr3.clear() is called.

Parameters:

mesh : The mesh that should be marked for deletion

gr3.drawconemesh(n, positions, directions, colors, radii, lengths)

This function allows drawing a cylinder without requiring a mesh.

See also

Function gr.drawmesh()

gr3.drawcylindermesh(n, positions, directions, colors, radii, lengths)

This function allows drawing a cylinder without requiring a mesh.

See also

Function gr.drawmesh()

gr3.drawspheremesh(n, positions, colors, radii)

This function allows drawing a sphere without requiring a mesh.

See also

Function gr.drawmesh()

gr3.createsurfacemesh(nx, ny, px, py, pz, option=0)

Create a mesh of a surface plot similar to gr_surface. Uses the current colormap. To apply changes of the colormap a new mesh has to be created.

Parameters:

mesh : the mesh handle

nx : number of points in x-direction

ny : number of points in y-direction

px : an array containing the x-coordinates

py : an array containing the y-coordinates

pz : an array of length nx * ny containing the z-coordinates

option : option for the surface mesh; the GR3_SURFACE constants can be combined with bitwise or. See the table below.

GR3_SURFACE_DEFAULT	0	default behavior
GR3_SURFACE_NORMALS	1	interpolate the vertex normals from the gradient
GR3_SURFACE_FLAT	2	set all z-coordinates to zero
GR3_SURFACE_GRTRANSFORM	4	use gr_inqwindow, gr_inqspace and gr_inqscale to transform the data to NDC coordinates
GR3_SURFACE_GRCOLOR	8	color the surface according to the current gr colormap
GR3_SURFACE_GRZSHADED	16	like GR3_SURFACE_GRCOLOR, but use the z-value directly as color index

gr3.drawmesh_grlike(mesh, n, positions, directions, ups, colors, scales)

Draw a mesh with the projection of gr. It uses the current projection parameters (rotation, tilt) of gr. This function alters the projection type, the projection parameters, the viewmatrix and the light direction. If necessary, the user has to save them before the call to this function and restore them after the call to gr3_drawimage.

Parameters:

mesh : the mesh to be drawn

n : the number of meshes to be drawn

positions : the positions where the meshes should be drawn

directions : the forward directions the meshes should be facing at

ups : the up directions

colors : the colors the meshes should be drawn in, it will be multiplied with each vertex color

scales : the scaling factors

gr3.drawsurface(mesh)

Convenience function for drawing a surfacemesh

Parameters:

mesh : the mesh to be drawn

gr3.surface(px, py, pz, option=0)

Create a surface plot with gr3 and draw it with gks as cellarray

Parameters:

nx : number of points in x-direction

ny : number of points in y-direction

px : an array containing the x-coordinates

py : an array containing the y-coordinates

pz : an array of length nx * ny containing the z-coordinates

option : see the option parameter of gr_surface. OPTION_COLORED_MESH and OPTION_Z_SHADED_MESH are supported.

Export and Drawing Functions

gr3.getimage(width, height, use_alpha=True)

gr3.drawimage(xmin, xmax, ymin, ymax, pixel_width, pixel_height, window)

gr3.export(filename, width, height)

gr3.setquality(quality)

Set rendering quality

Parameters:

quality:

The quality to set

Interaction Functions