OGRE 3D Visualiser

Detailed Description

ovis is a simplified rendering wrapper around ogre3d. The Ogre terminology is used in the API and Ogre Script is assumed to be used for advanced customization.

Besides the API you see here, there are several environment variables that control the behavior of ovis. They are documented in createWindow.

Loading geometry

You can create geometry on the fly or by loading Ogre .mesh files.

Blender

For converting/ creating geometry Blender is recommended.

• Blender 2.7x is better tested, but Blender 2.8x should work too
• install blender2ogre matching your Blender version
• download the Ogre MSVC SDK which contains OgreXMLConverter.exe (in bin/) and set the path in the blender2ogre settings
• get ogre-meshviewer to enable the preview function in blender2ogre as well as for verifying the exported files
• in case the exported materials are not exactly how you want them, consult the Ogre Manual

Assimp

When using Ogre 1.12.9 or later, enabling the Assimp plugin allows to load arbitrary geometry. Simply pass bunny.obj instead of bunny.mesh as meshname in WindowScene::createEntity.

You should still use ogre-meshviewer to verify that the geometry is converted correctly.

Classes
class	cv::ovis::WindowScene

Enumerations
enum	cv::ovis::EntityProperty {   cv::ovis::ENTITY_MATERIAL ,   cv::ovis::ENTITY_SCALE ,   cv::ovis::ENTITY_AABB_WORLD ,   cv::ovis::ENTITY_ANIMBLEND_MODE ,   cv::ovis::ENTITY_CAST_SHADOWS }
enum	cv::ovis::MaterialProperty {   cv::ovis::MATERIAL_POINT_SIZE ,   cv::ovis::MATERIAL_LINE_WIDTH ,   cv::ovis::MATERIAL_OPACITY ,   cv::ovis::MATERIAL_EMISSIVE ,   cv::ovis::MATERIAL_DIFFUSE ,   cv::ovis::MATERIAL_TEXTURE0 ,   cv::ovis::MATERIAL_TEXTURE = MATERIAL_TEXTURE0 ,   cv::ovis::MATERIAL_TEXTURE1 ,   cv::ovis::MATERIAL_TEXTURE2 ,   cv::ovis::MATERIAL_TEXTURE3 }
enum	cv::ovis::SceneSettings {   cv::ovis::SCENE_SEPARATE = 1 ,   cv::ovis::SCENE_INTERACTIVE = 2 ,   cv::ovis::SCENE_SHOW_CS_CROSS = 4 ,   cv::ovis::SCENE_AA = 8 ,   cv::ovis::SCENE_OFFSCREEN = 16 ,   cv::ovis::SCENE_SHADOWS = 32 }

Functions
void	cv::ovis::addResourceLocation (const String &path)
void	cv::ovis::createGridMesh (const String &name, const Size2f &size, const Size &segments=Size(1, 1))
void	cv::ovis::createPlaneMesh (const String &name, const Size2f &size, InputArray image=noArray())
void	cv::ovis::createPointCloudMesh (const String &name, InputArray vertices, InputArray colors=noArray())
void	cv::ovis::createTriangleMesh (const String &name, InputArray vertices, InputArray normals=noArray(), InputArray indices=noArray())
Ptr< WindowScene >	cv::ovis::createWindow (const String &title, const Size &size, int flags=SCENE_INTERACTIVE|SCENE_AA)
void	cv::ovis::setMaterialProperty (const String &name, const String &prop, const Scalar &value)
void	cv::ovis::setMaterialProperty (const String &name, int prop, const Scalar &value)
void	cv::ovis::setMaterialProperty (const String &name, int prop, const String &value)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	cv::ovis::setMaterialProperty (const String &name, int prop, InputArray value)
void	cv::ovis::updateTexture (const String &name, InputArray image)
int	cv::ovis::waitKey (int delay=0)

Enumeration Type Documentation

EntityProperty

enum cv::ovis::EntityProperty

#include <opencv2/ovis.hpp>

Enumerator
ENTITY_MATERIAL
ENTITY_SCALE
ENTITY_AABB_WORLD
ENTITY_ANIMBLEND_MODE
ENTITY_CAST_SHADOWS

MaterialProperty

enum cv::ovis::MaterialProperty

#include <opencv2/ovis.hpp>

Enumerator
MATERIAL_POINT_SIZE
MATERIAL_LINE_WIDTH
MATERIAL_OPACITY
MATERIAL_EMISSIVE
MATERIAL_DIFFUSE
MATERIAL_TEXTURE0
MATERIAL_TEXTURE
MATERIAL_TEXTURE1
MATERIAL_TEXTURE2
MATERIAL_TEXTURE3

SceneSettings

enum cv::ovis::SceneSettings

#include <opencv2/ovis.hpp>

Enumerator
SCENE_SEPARATE	the window will use a separate scene. The scene will be shared otherwise.
SCENE_INTERACTIVE	allow the user to control the camera.
SCENE_SHOW_CS_CROSS	draw coordinate system crosses for debugging
SCENE_AA	Apply anti-aliasing. The first window determines the setting for all windows.
SCENE_OFFSCREEN	Render off-screen without a window. Allows separate AA setting. Requires manual update via WindowScene::update.
SCENE_SHADOWS	Enable real-time shadows in the scene. All entities cast shadows by default. Control via ENTITY_CAST_SHADOWS.

Function Documentation

addResourceLocation()

void cv::ovis::addResourceLocation

(

const String &

path

)

#include <opencv2/ovis.hpp>

Add an additional resource location that is search for meshes, textures and materials

must be called before the first createWindow. If give path does not exist, retries inside Ogre Media Directory.

Parameters

path	folder or Zip archive.

createGridMesh()

void cv::ovis::createGridMesh	(	const String &	name,
		const Size2f &	size,
		const Size &	segments = Size(1, 1)
	)

#include <opencv2/ovis.hpp>

creates a grid

creates a material with the same name

Parameters

name	name of the mesh
size	extents of the grid
segments	number of segments per side

createPlaneMesh()

void cv::ovis::createPlaneMesh	(	const String &	name,
		const Size2f &	size,
		InputArray	image = noArray()
	)

#include <opencv2/ovis.hpp>

create a 2D plane, X right, Y down, Z up

creates a material with the same name

Parameters

name	name of the mesh
size	size in world units
image	optional texture

createPointCloudMesh()

void cv::ovis::createPointCloudMesh	(	const String &	name,
		InputArray	vertices,
		InputArray	colors = noArray()
	)

#include <opencv2/ovis.hpp>

creates a point cloud mesh

creates a material with the same name

Parameters

name	name of the mesh
vertices	float vector of positions
colors	uchar vector of colors

createTriangleMesh()

void cv::ovis::createTriangleMesh	(	const String &	name,
		InputArray	vertices,
		InputArray	normals = noArray(),
		InputArray	indices = noArray()
	)

#include <opencv2/ovis.hpp>

creates a triangle mesh from vertex-vertex or face-vertex representation

creates a material with the same name

Parameters

name	name of the mesh
vertices	float vector of positions
normals	float vector of normals
indices	int vector of indices

createWindow()

Ptr< WindowScene > cv::ovis::createWindow	(	const String &	title,
		const Size &	size,
		int	flags = SCENE_INTERACTIVE|SCENE_AA
	)

#include <opencv2/ovis.hpp>

create a new rendering window/ viewport

Parameters

title	window title
size	size of the window
flags	a combination of SceneSettings

Furthermore, the behavior is controlled by the following environment variables

• OPENCV_OVIS_VERBOSE_LOG: print all of OGRE log output
• OPENCV_OVIS_RENDERSYSTEM: the name of the OGRE RenderSystem to use
• OPENCV_OVIS_NOVSYNC: disable VSYNC for all windows

setMaterialProperty() [1/4]

void cv::ovis::setMaterialProperty	(	const String &	name,
		const String &	prop,
		const Scalar &	value
	)

#include <opencv2/ovis.hpp>

set the shader property of a material to the given value

Parameters

name	material name
prop	property name
value	the value

setMaterialProperty() [2/4]

void cv::ovis::setMaterialProperty	(	const String &	name,
		int	prop,
		const Scalar &	value
	)

#include <opencv2/ovis.hpp>

set the property of a material to the given value

Parameters

name	material name
prop	MaterialProperty
value	the value

setMaterialProperty() [3/4]

void cv::ovis::setMaterialProperty	(	const String &	name,
		int	prop,
		const String &	value
	)

#include <opencv2/ovis.hpp>

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setMaterialProperty() [4/4]

void cv::ovis::setMaterialProperty	(	const String &	name,
		int	prop,
		InputArray	value
	)

#include <opencv2/ovis.hpp>

set the texture of a material to the given value

Parameters

name	material name
prop	MaterialProperty
value	the texture data

updateTexture()

void cv::ovis::updateTexture	(	const String &	name,
		InputArray	image
	)

#include <opencv2/ovis.hpp>

Deprecated:

use setMaterialProperty

waitKey()

int cv::ovis::waitKey

(

int

delay = 0

)

#include <opencv2/ovis.hpp>

update all windows and wait for keyboard event

Parameters

delay

0 is the special value that means "forever". Any positive number returns after sync to blank (typically 16ms).

Returns

the code of the pressed key or -1 if no key was pressed