IMG3D_Manager Class Reference

Class to handle reading/writing 3D texture images. More...

#include <IMG3D_Manager.h>

Public Member Functions
	IMG3D_Manager ()
	~IMG3D_Manager ()
int	closeTexture ()
int	openTexture (const char *filename)
const float *	getCorner () const
const float *	getSize () const
const int *	getRes () const
	Returns the number of voxels in x, y, z. More...
int	getNChannels () const
	Number of channels in the texture image. More...
const char *	getChannelName (int idx) const
	Query channel names. More...
int	getChannelSize (int idx) const
	Return the number of floats in the given channel. More...
int	getChannelNumber (const char *name) const
	Find the index of a named channel. Returns -1 if not found. More...
int	openChannel (const char *channel_name)
int	setFilter (const char *filter_name, fpreal filter_width)
int	sample (const UT_Vector3 &pos, float *result)
int	gradient (const UT_Vector3 &pos, float *result)
int	integrate (UT_Vector3 &p0, UT_Vector3 &p1, float *result, fpreal limit_max=1, fpreal value_scale=1, fpreal accuracy=0)
int	intersect (UT_Vector3 &p0, const UT_Vector3 &p1, fpreal density, fpreal accuracy=1e-5F)
float *	loadUntiledChannel ()
int	loadUntiledChannel (float *data)
	Same as loadUntitledChannel() but fills a user-allocated array. More...
int	createTexture (const char *filename, const UT_BoundingBox &box, int xres, int yres, int zres, int compression=5)
int	fillTexture (int num_channels, const char *channel_names[], int channel_sizes[], IMG3D_TextureEval evaluator, int max_samples=4, fpreal variance=0.005, fpreal filter_width=1, fpreal jitter=1)
int	fillUntiledTexture (int num_channels, const char *channel_names[], int channel_sizes[], const float *data[], fpreal variance=0.005)
bool	exportTag (const char *name, int value)
bool	exportTag (const char *name, float value)
bool	exportTag (const char *name, const UT_Vector3 &value)
bool	exportTag (const char *name, const UT_Vector4 &value)
bool	exportTag (const char *name, const UT_Matrix3 &value)
bool	exportTag (const char *name, const UT_Matrix4 &value)
bool	exportTag (const char *name, const char *value)
bool	importTag (const char *name, int &value)
bool	importTag (const char *name, float &value)
bool	importTag (const char *name, UT_Vector3 &value)
bool	importTag (const char *name, UT_Vector4 &value)
bool	importTag (const char *name, UT_Matrix3 &value)
bool	importTag (const char *name, UT_Matrix4 &value)
bool	importTag (const char *name, UT_String &value)

Protected Attributes
void *	myData

Detailed Description

Class to handle reading/writing 3D texture images.

A 3D texture file is similar to a 2D texture file, but with an added dimension. The 3D texture is broken down into 3D tiles. Each tile is stored independently in the file. This allows for partial loading of the 3D texture (without having to load the entire image at one time).

However, the tiled approach makes it difficult to create images since the writer works on a single tile at a time.

Just like image files, the 3D texture file can have an arbitrary number of channels, each with its own name, storage and tuple size.

In order to read an 3D texture, you have to open both an image and a channel:

IMG3D_Manager       fp;
int         channel_index;
fp.openTexture(filename);
fp.openChannel(channel);

Examples:

standalone/i3ddsmgen.C, and standalone/i3dsphere.C.

Definition at line 69 of file IMG3D_Manager.h.

Constructor & Destructor Documentation

IMG3D_Manager::IMG3D_Manager

(

)

IMG3D_Manager::~IMG3D_Manager

(

)

Member Function Documentation

int IMG3D_Manager::closeTexture

(

)

Close the file (whether opened for read or write). This is done automatically on destruction.

Examples:

standalone/i3dsphere.C.

int IMG3D_Manager::createTexture	(	const char *	filename,
		const UT_BoundingBox &	box,
		int	xres,
		int	yres,
		int	zres,
		int	compression = 5
	)

This method allows the creation of a 3D texture. The bounding box defines the are where the map is sampled.

Compression is the level of gzip compression to use. Valid values are between 0 (no compression) and 9 (maximum compression).

Examples:

standalone/i3dsphere.C.

bool IMG3D_Manager::exportTag	(	const char *	name,
		int	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

Examples:

standalone/i3dsphere.C.

bool IMG3D_Manager::exportTag	(	const char *	name,
		float	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

bool IMG3D_Manager::exportTag	(	const char *	name,
		const UT_Vector3 &	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

bool IMG3D_Manager::exportTag	(	const char *	name,
		const UT_Vector4 &	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

bool IMG3D_Manager::exportTag	(	const char *	name,
		const UT_Matrix3 &	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

bool IMG3D_Manager::exportTag	(	const char *	name,
		const UT_Matrix4 &	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

bool IMG3D_Manager::exportTag	(	const char *	name,
		const char *	value
	)

It's possible store and retrieve tags (based on the read/write mode of the file). These tags can be queried using texinfo() in VEX.

int IMG3D_Manager::fillTexture	(	int	num_channels,
		const char *	channel_names[],
		int	channel_sizes[],
		IMG3D_TextureEval	evaluator,
		int	max_samples = 4,
		fpreal	variance = 0.005,
		fpreal	filter_width = 1,
		fpreal	jitter = 1
	)

Once the texture is created, please call the following code to generate the values for the texture.

Parameters

num_channels	The number of channels
channel_names	An array of channel names
channel_sizes	The number of floats in each channel.
evaluator	Callback to evaluate channel positions
max_samples	Anti-aliasing samples
variance	Variance threshhold for anti-aliasing to occur
filter_width	Anti-aliasing filter width
jitter	Amount of jitter for anti-aliasing

Note

currently, only box filtering is supported for anti-aliasing

Returns

0 if the process fails.

Examples:

standalone/i3dsphere.C.

int IMG3D_Manager::fillUntiledTexture	(	int	num_channels,
		const char *	channel_names[],
		int	channel_sizes[],
		const float *	data[],
		fpreal	variance = 0.005
	)

Save flat untiled data to the file. This method perfoms the inverse operation of loadUntiledChannel, but for multiple channels.

Parameters

num_channels	- The number of channels
channel_names	- An array of channel names
channel_sizes	- The number of floats in each channel
data	- Source data for each channel
variance	- Ignored

Given the getRes() function returning W, H, D (width, height, depth), the data array for channel i must be W*H*D * channel_sizes[i] * sizeof(float) bytes long. Given an index (ix, iy, iz), the channel data can be indexed by: ix + iy*W + iz*W*H

Returns

0 if the process fails.

const char* IMG3D_Manager::getChannelName

(

int

idx

)

const

Query channel names.

int IMG3D_Manager::getChannelNumber

(

const char *

name

)

const

Find the index of a named channel. Returns -1 if not found.

int IMG3D_Manager::getChannelSize

(

int

idx

)

const

Return the number of floats in the given channel.

const float* IMG3D_Manager::getCorner

(

)

const

Returns an array of 3 floats for xmin(), ymin(), zmin() representing the left, bottom, front corner of the 3D texture.

int IMG3D_Manager::getNChannels

(

)

const

Number of channels in the texture image.

const int* IMG3D_Manager::getRes

(

)

const

Returns the number of voxels in x, y, z.

const float* IMG3D_Manager::getSize

(

)

const

Returns an array of 3 floats for xsize(), ysize(), zsize() representing the size of the bounding box.

int IMG3D_Manager::gradient	(	const UT_Vector3 &	pos,
		float *	result
	)

Evaluate the gradient of the 3D texture at the given position. Uses the filter set by setFilter().

Note

The gradient can only be computed on scalar channels.

3 floats will be returned for a scalar channel.

bool IMG3D_Manager::importTag	(	const char *	name,
		int &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

bool IMG3D_Manager::importTag	(	const char *	name,
		float &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

bool IMG3D_Manager::importTag	(	const char *	name,
		UT_Vector3 &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

bool IMG3D_Manager::importTag	(	const char *	name,
		UT_Vector4 &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

bool IMG3D_Manager::importTag	(	const char *	name,
		UT_Matrix3 &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

bool IMG3D_Manager::importTag	(	const char *	name,
		UT_Matrix4 &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

bool IMG3D_Manager::importTag	(	const char *	name,
		UT_String &	value
	)

When importing, if the type doesn't match, casting will be done (where possible). Importing a string is always possible. If the import fails, the value will be untouched and the import will return false.

int IMG3D_Manager::integrate	(	UT_Vector3 &	p0,
		UT_Vector3 &	p1,
		float *	result,
		fpreal	limit_max = 1,
		fpreal	value_scale = 1,
		fpreal	accuracy = 0
	)

Integrate from p0 to p1 and return the integration result. Optional controls are:

Parameters

p0	Start of integration
p1	End of integration
result	Integration result. This should large enough to hold getChannelSize() floats.
limit_max	if this value of the integration exceeds this value, then the integration will be terminated early.
value_scale	scale the integration value by this amount. This scaling is applied BEFORE limit checks.
accuracy	A scaling on stepping. Increasing the accuracy will perform more sub-steps on the integration, yielding a more accurate result (at a higher cost). Increasing the accuracy can have a significant effect on performance.

As a result of integration, p1 will be clipped to the bounds of the texture. As well, p0 will be moved to the point where the limit was reached (if the limit was reached).

Examples:

standalone/i3ddsmgen.C.

int IMG3D_Manager::intersect	(	UT_Vector3 &	p0,
		const UT_Vector3 &	p1,
		fpreal	density,
		fpreal	accuracy = 1e-5F
	)

Find the intersection against the iso-surface defined by density specified. The accuracy is how close f(p0) will be to zero. If an intersection is found, the function will return 1. p0 will be moved to the intersection point (or to p1 if there was no intersection found).

float* IMG3D_Manager::loadUntiledChannel

(

)

Load a channel as a flat list of floats. The data is allocated using malloc(). It's the users responsibility for freeing this memory using free(). Given the getRes() function returning W, H, D (width, height, depth), the array returned will be W*H*D * getChannelSize() * sizeof(float) bytes long. Given an index (ix, iy, iz), the channel data can be indexed by: ix + iy*W + iz*W*H

int IMG3D_Manager::loadUntiledChannel

(

float *

data

)

Same as loadUntitledChannel() but fills a user-allocated array.

int IMG3D_Manager::openChannel

(

const char *

channel_name

)

Once a texture is open, you must open a handle to a channel to be able to access data in the channel. Returns 0 on failure or 1 on success.

Note

Only a single channel can be open per manager.

Examples:

standalone/i3ddsmgen.C.

int IMG3D_Manager::openTexture

(

const char *

filename

)

Open a texture for reading. Returns 0 if there was an error opening the file.

Examples:

standalone/i3ddsmgen.C.

int IMG3D_Manager::sample	(	const UT_Vector3 &	pos,
		float *	result
	)

Evaluate the 3D texture at the given position. Returns 0 on failure. Uses the filter set by setFilter().

Note

The result buffer should have enough storage to hold getChannelSize().

Examples:

standalone/i3ddsmgen.C.

int IMG3D_Manager::setFilter	(	const char *	filter_name,
		fpreal	filter_width
	)

Set the evaluation filter. This filter filter can be any one of the standard Houdini filter types. The filtering is use for evaluation and integration of the texture. Returns 0 on failure.

See Also

UT_Filter.

Member Data Documentation

void* IMG3D_Manager::myData

protected

Definition at line 312 of file IMG3D_Manager.h.

---

The documentation for this class was generated from the following file:

• IMG3D/IMG3D_Manager.h