forked from magic-box/Field3DMayaPlugin
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
206 lines (155 loc) · 7.19 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
------------------------------------------------------------------------
ABOUT THE FIELD3D PLUGIN FOR MAYA
------------------------------------------------------------------------
Field3D is an open source library for storing voxel data developed
originaly at Sony Pictures Imageworks. It provides C++ classes that
handle in-memory storage and a file format based on HDF5 that
allows the C++ objects to be written to and read from disk.
This plugin aims to integrate Field3D into Maya. The main benefits
of using field3d are:
- open format supported in several softwares ( especially
Houdini)
- efficient memory compression by using sparse Field in either
float or half type.
- handling of huge amount of voxel thanks to the use of Hdf5
under the hood.
More information about Field3D can be found at:
http://sites.google.com/site/field3d/
http://code.google.com/p/field3d/
------------------------------------------------------------------------
LICENSE
------------------------------------------------------------------------
The plugin source code is distributed under the "New BSD" license.
See the file called COPYING for details.
------------------------------------------------------------------------
PLUGIN DEPENDENCIES
------------------------------------------------------------------------
This Plugin was originally developed under Fedora 13 (Goddard) for
Maya 2011(sp1). It has been tested with gcc 4.1.2 and maya 2011(sp1).
The libraries required for this plugin are:
IlmBase ( 1.0.2 )
HDF5 ( 1.8.7 )
Field3D ( 1.2.0 )
maya SDK ( 2011 )
Other versions of these libraries might work, but they haven't been
tested yet.
The make system used by this plugin is cmake ( http://www.cmake.org/ ).
But it might be also possible to create easily your own Makefile. In this
case, have a look at the CMakeLists.txt .
More information about HDF5 can be found at:
http://www.hdfgroup.org/HDF5/
More information about IlmBase/OpenEXR can be found at:
http://www.openexr.com/
More information about Field3D can be found at:
http://sites.google.com/site/field3d
------------------------------------------------------------------------
BUILDING THIS PLUGIN
------------------------------------------------------------------------
This plugin was originally developed under Fedora 13 (Goddard) and
gcc 4.1.2
The make system used by this plugin is cmake ( http://www.cmake.org/ ).
It is mandatory to use gcc 4.1.2 if you intend to compile the plugin for
maya 2011(sp1). Other version of maya haven't been tested yet.
To build the plugin, go to the plugin directory and type :
$ ccmake ./CMakeLists.txt
You can specify the compiler you want to use while invoking
cmake this way:
$ ccmake ./CMakeLists.txt -DCMAKE_C_COMPILER=/path/to/gcc
-DCMAKE_CXX_COMPILER=/path/to/g++
You have to specify four paths :
FIELD3D_ROOT_DIR
HDF5_ROOT_DIR
ILMBASE_ROOT_DIR
MAYA_ROOT_DIR
In each of those root paths must reside a "lib" and an "include"
directory. They will be found automatically.
Alternatively, you can invoke ccmake with arguments in a script :
#!/bin/sh
ccmake \
./CMakeLists.txt \
-DFIELD3D_ROOT_DIR=/path/to/field3D \
-DHDF5_ROOT_DIR=/path/to/hdf5 \
-DILMBASE_ROOT_DIR=/path/to/ilmbase \
-DMAYA_ROOT_DIR=/path/to/maya
This will build a shared library (*.so), that you can load with the Maya
Plugin Manager. By default an optimized/release build is created.
You can output log messages on the console by compiling in debug mode.
If you don't want any log message, add -DNDEBUG to CMAKE_CXX_FLAGS in
cmake advanced mode.
You can link statically or dynamically to the required libraries.
Static link is probably the prefered way, as it is simple to deploy.
If you choose to link dynamically, be sure to set your LD_LIBRARY_PATH
to those directories before launchin Maya :
/path/to/field3D/lib
/path/to/hdf5/lib
/path/to/ilmbase/lib
/path/to/maya/lib
/path/to/boost/lib ( needed by field3D )
Finally, if you are concerned by the performance of the cache format ,
you could turn off the gzip compression used by default in Field3D by
modifiying the function "bool checkHdf5Gzip()" in Hdf5Util.cpp :
bool checkHdf5Gzip()
{
// manually disabled for performance reasons.
printf("checkHdf5Gzip disabled\n");
return false;
/* comment the original function
htri_t avail = H5Zfilter_avail(H5Z_FILTER_DEFLATE);
if (!avail)
return false;
unsigned int filter_info;
herr_t status = H5Zget_filter_info (H5Z_FILTER_DEFLATE, &filter_info);
if (status < 0)
return false;
if (!(filter_info & H5Z_FILTER_CONFIG_ENCODE_ENABLED) ||
!(filter_info & H5Z_FILTER_CONFIG_DECODE_ENABLED)) {
return false;
}
return true;
*/
}
Our benchmarks have shown a important improvement in term of speed
( but obviously not in term of storage usage).
------------------------------------------------------------------------
USING THE PLUGIN
------------------------------------------------------------------------
Once the library is compiled, open Maya and load it with Windows -> Settings/
Preferences -> Plugin Manager.
Create a scene with a fluid. Then go to Fluid nCache -> Create New
Cache (advanced tab) -> Cache format. Now you can choose between different
kind of field3d formats.
The plugin currently supports two types of fields:
- Dense fields are similar to .mcc format : Values are stored in
a regular grid.
- Sparse fields are different from dense fields primarily in that
they don't allocate space for voxels until they are actually in use
Thus in many cases sparse fields require less memory on disk than a regular
dense field. A sparse field use a threshold to ignore part of the data which
are not meaningful. It is currently set to 0.0000001 which should suffice in
most cases. You can modify it in field3D_Tools.h if you need it:
( const float SPARSE_THRESHOLD = 0.0000001 ; )
The plugin supports also two kind of type of data :
- float : floating point stored on 4 bytes
- half : floating point stored on 2 bytes ( from IlmBase )
The data type is the internal representation of a single value ( density,
temperature, pressure, etc .) in the field.
As a consequence, fields using half type require twice as less memory on disk
than their float counterparts. But keep in mind that half type can lead
to numerical inaccuracies as they are twice less precise than a float.
Use them with care !
------------------------------------------------------------------------
CURRENT LIMITATIONS - FUTUR WORK
------------------------------------------------------------------------
Sequence can't currently be saved into one single file. The methods
beginReadChunk(), endReadChunk(), beginWriteChunk(), and endWriteChunk()
have still to be written.
------------------------------------------------------------------------
AUTHOR
------------------------------------------------------------------------
Original development at Prime Focus Film London:
Antoine P.
------------------------------------------------------------------------
QUESTIONS AND COMMENTS
------------------------------------------------------------------------
For questions and/or comments, please feel free to send an email at :
git.magic.box@gmail.com