The build3d_2 user macro reads a series of image files and outputs this data as a uniform volume field. The source image files can be of any the formats supported by AVS/Express. The output contains a single node data component. This component can be either a 4 byte vector containing the full ARGB data, a 3 float vector containing the RGB data, a single byte containing the value of a single channel or a single float containing the luminance of each pixel.
| Name | Type | Description | UI Control |
| filename_head | string | Portion of filename before index. | Text Box |
| filename_tail | string | Portion of filename after index. | Text Box |
| min_length | int | Minimum length of index. | Field Box |
| start | int | Starting index of filenames. | Field Box |
| end | int | Ending index of filenames. | Field Box |
| format | int | Format of input image files. | Radiobox |
| out_format | int | Format of output node data. | Radiobox |
| Name | Type | Description | |
| out_fld | Field | Output uniform 3D field data. | |
| out_obj | DataObject | Directly renderable output object. | |
The build3d_2 user macro reads in a series of image file slices, builds these slices into a 3D volume and then outputs this data as a 3D uniform field. The format of the input image files can be explicitly specified or can be automatically detected. The format of the output data can also be specified. The macro can output node data that for each node contains either a 4 byte vector containing the full-colour ARGB image data, a 3 float vector containing the RGB image data, a single byte containing a single channel of the image data or a single float containing the luminance of the pixel.
The macro selects which files should be read by looking for a series of filenames that are identical accept for a changing index number. All files read by the build3d_2 macro must contain an index number. The macro cannot read an arbitrary sequence of files. The names of the files to read are specified by 3 parameters, a filename head, a filename tail and a minimum index length. The filename head is the portion of the filename that appears before the index. The filename tail is the portion of the filename that appears after the index. The minimum length specifies the shortest possible length of the index number. If the index number is shorter than this the remainder of the index is padded with zero characters. Hence if you had filenames of the form pic001.tif then the 3 parameters would have the values:
| Filename Head | pic |
| Filename Tail | .tif |
| Minimum Length | 3 |
To help the user adjust these properties the user interface displays an example of how they will be used to create a real filename. After the filename parameters have been specified the user must also specify which indexed files should be read. This is done be specifying a starting index and an ending index. The sequence of filenames generated proceeds from the start index to the end index. The sequence includes the image file with the ending index number.
The build3d_2 macro will ensure that all the specified image files exist, are of the same format and are the same size. If they are not the macro will stop with an error message.
It should be noted that this macro outputs a uniform field and hence it assumes that all the input slices are evenly spaced. If this not the case then the adjust_slice_spacing macro can be used to convert the uniform field into a rectilinear field with specified positions for each slice.
The build3d_2 macro can be useful in a wide variety of situations. For instance in microscopy a series of images can be taken at different depths. The build3d_2 macro can take these separate images and build them into a 3D volume that can be visualized as a whole. The example applications illustrates this and also illustrates now the image data can be used to colour AVS/Express fields. This could be used, for instance to realistically colour an isosurface visualization of a body.
filename_head
String parameter that specifies the portion of the image filename that appears before the index number. If the image files are stored in a directory other than the current directory the directory name should be given in this parameter. The directory name can be either relative or absolute and it can contain AVS/Express environment variables (i.e. $XP_ROOT, $XP_PATH<1>).
filename_tail
String parameter that specifies the portion of the image filename that appears after the index number. The parameter can contain AVS/Express environment variables (i.e. $XP_ROOT, $XP_PATH<1>).
min_length
Integer parameter that specifies the minimum length of the index number in the filename. If the actual index number is shorter than this length the index will be padded with zeros. Using this parameter allows files with a constant index length to be read.
Filename Example
Output string parameter that is intended to show how the filename parameters will be used to create indexed filenames. The parameter shows what the filename would be for the file indexed 1. This parameter is intended as an output only and does not need to be altered.
start
Integer parameter that specifies the index number of the first image that should be read. This parameter must be less than the end parameter.
end
Integer parameter that specifies the index number of the last image that should be read. This parameter must be greater than the start parameter.
format
Integer parameter that specifies the format of the image files that are been read. If the format is not known then no value or a value of 0 can be given. This indicates that the macro should automatically detect the format of the image files.
The following values are valid for this parameter. Normally the image file format will be chosen by selecting an option from the radio box.
out_format
Integer parameter that specifies the format of the output node data. Along with the uniform mesh the build3d_2 macro outputs a single node data component. This node data component can contain one of several different types of data. This parameter specifies what data should be output for each node.
The following values are valid for this parameter. Normally the output format will be chosen by selecting an option from the radio box.
The floating point luminance values are calculated by the following formula and are scaled so that all values lie in the range 0 to 1.
luminance = (red*0.299) + (green*0.587) + (blue*0.114)
The formats of the 4 byte ARGB and 3 float RGB outputs where chosen so that they would directly map to special forms of node data used by AVS/Express. If certain node data ID numbers are specified Express will use the output node data to directly colour the mesh that it renders. Hence the colours in the input images can be used to render the final visualization. Unfortunately due to a problem with Express the required node data IDs cannot be set by the build3d_2 macro. Instead the node_2_argb_data and node_2_color_data modules have to be used instead. It should be noted that Express will only use 4 byte ARGB data to colour 2D fields such as orthoslices.
out_fld
The output uniform volume field. The output field contains a uniform mesh and a single component of node data. The dimensions of the mesh are set by the width and height of the images and the number of image slices read. The node data component can contain a 4 byte vector, a 3 float vector, a single byte scalar or a single float scalar depending upon which output option is choose.
out_obj
The directly renderable output of the build3d_2 macro. Normally this output will not be used as other visualizations will have to be done before the data can be displayed.
The low-level Build3D_2_Core module is used in the Functional Macro Build3D_2_Func which is in turn used in the User Macro build3d_2. Additionally, this macro also uses the Build3D_2_Params parameter block group object, as does the Build3D_2_UI UI Macro.
The adjust_slice_spacing utility macro is also provided. This macro enables the slice spacing of a uniform volume to be adjusted. A rectilinear field is then output. If the input image slices were taken at an irregular spacing this macro enables the spacing of the build3d_2 output to be corrected.
The node_2_argb_data and node_2_color_data modules are also provided. These modules take an input field and sets the appropriate node data ID so that Express can use the colour data to directly render the output mesh. The node_2_argb_data module sets the node data ID to GD_RGB_DATA_ID and the node_2_color_data module sets the node data ID to GD_COLOR_DATA_ID. Both of these modules should be placed at the end of the visualization pipeline immediately before the viewer component. Examples of their use can be seen in the NodeARGBDataEg and NodeColorDataEg example applications.
Four example applications are provided. The Build3D_2_Eg application loads a series of 30 TIFF images, builds a 3D volume from these and displays the volume using an orthoslice and a bounding box. The AdjustSliceSpacingEg application similarly loads a series of TIFF images. However this application also uses the adjust_slice_spacing user macro to irregularly space the image slices. You should be able to see that the orthoslice does not now move up and down in uniform steps.
The NodeARGBDataEg and NodeColorDataEg example applications illustrate how colour from images can be used to colour a final visualization. The NodeARGBDataEg application reads a small set of colour images and displays an orthoslice of the volume. This orthoslice has the same colouring as the original images. No 3D fields are coloured as Express does not support using ARGB data to colour 3D fields. In a similar way the NodeColorDataEg application reads the set of colour images. However it displays both a coloured orthoslice and a coloured isosurface. This illustrates that it is possible to use image data to colour 3D fields.
iac_proj/build3d_2/bl3dmods.v contains the V definitions of the Build3D_2_Params parameter group and the Build3D_2_Core and AdjustSliceSpacingCore low-level modules.
iac_proj/build3d_2/bl3dmacs.v contains the V definitions of the Build3D_2_UI UI Macro, the Build3D_2_Func, node_2_argb_data and node_2_color_data Functional Macros and the build3d_2 and adjust_slice_spacing User Macros.
iac_proj/build3d_2/bl3dapps.v contains the V definitions of the Build3D_2_Eg, AdjustSliceSpacingEg, NodeARGBDataEg and NodeColorDataEg example applications.
The low-level Build3D_2_Mods library containing the low-level Build3DCore and AdjustSliceSpacingCore modules does not specify a process. By default the express process will be used.
Andrew Dodd International AVS Centre
International AVS Centre Manchester Visualization Centre Manchester Computing University of Manchester Oxford Road Manchester United Kingdom M13 9PL