HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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 intgetRes () 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

voidmyData
 

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:

int channel_index;
fp.openTexture(filename);
fp.openChannel(channel);
Examples:
standalone/i3ddsmgen.C, and standalone/i3dsphere.C.

Definition at line 68 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_channelsThe number of channels
channel_namesAn array of channel names
channel_sizesThe number of floats in each channel.
evaluatorCallback to evaluate channel positions
max_samplesAnti-aliasing samples
varianceVariance threshhold for anti-aliasing to occur
filter_widthAnti-aliasing filter width
jitterAmount 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
p0Start of integration
p1End of integration
resultIntegration result. This should large enough to hold getChannelSize() floats.
limit_maxif this value of the integration exceeds this value, then the integration will be terminated early.
value_scalescale the integration value by this amount. This scaling is applied BEFORE limit checks.
accuracyA 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 308 of file IMG3D_Manager.h.


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