PLEASE NOTE : This is the documentation for the avs module executable convert_data, which contains the following modules: vband2vect vbandcomb vbandspt1 vbandspt3 vcast vconvert vctor vect2band vect2row vmos2band vrect2pol vrtoc Any mention of xvimage is actually a "field 2D". Also, the INPUTs and OUTPUTs, which are mapped to avs parameters, inputs, and outputs, are for the khoros library routine. ******************************************************************************** Documentation for avs module vband2vect INPUT *image pointer to the input/output xvimage structure OUTPUT *image pointer to the input/output (struct xvimage) DESCRIPTION band2vect reformats data stored in a band type image format to a single-row of vectors or pixels. Each vector or pixel in the output file is comprised of a single band of data from the input image. The subrow size in the output file is set to reflect the number of rows in each band of the input image. Thus the size of each vector or pixel is determined by the number of rows and columns in each band of the input image. The number of vectors or pixels in the resulting output file is equal to the number of bands in the input image. Thus each vector of the output file represents a band of data from the input image. Each row of a band of data is stacked end to end as a vector in the resulting out- put file. For example, if an input file contained 3 bands of data with 2 rows and 5 columns in each band, then the output file would contain 3 vectors or pixels with a dimension of 10. That is, each vector would contain the data from one band of the input image. The dimension of each vector is equal to the number of rows * columns from a band of the input image. The subrow size is set to the number of rows in each band, or 2 in this particular case. The subrow size is carried along in the image header so that it will be possible to reconstruct the image band format of this file (see vect2band). The data storage type of the output image will be of the same type as the input image. This routine will accept any data storage type, except BIT. The valid map schemes are NONE, ONEPERBAND, and SHARED. Map schemes of CYCLE and GROUP are not supported at this time. Note that a map scheme of GROUP may be appropriate for this transformation, but is not yet defined. A map scheme of GROUP could be used to define a map for a pixel that is represented as a vector in the output file. Valid map scheme and map enable combinations include: single band image with map scheme of ONEPERBAND and a map enable of either FORCE or OPTIONAL. single band image with map scheme of SHARED and a map enable of either FORCE or OPTIONAL. multiband image with a map scheme of SHARED and a map enable of either FORCE or OPTIONAL. single or multiband image with a map scheme of NONE. The map may also be removed from an image by using "vrem- map", or the data may need to be mapped through the map using "vmapdata" prior to using this routine. The argument, image represents the input/output viff image structure. SEE ALSO band2vect(1), intro(3), vipl(3), verror(3), vutils(3) dload_vector(), unload_vector(), ect2band(3). RESTRICTIONS Will not operate on VFF_TYP_BIT data files. Will not work with the following map_scheme combinations: Multiband image with MS_ONEPERBAND and MAP_OPTIONAL Multiband image with MS_ONEPERBAND and MAP_FORCE Any map scheme with MS_CYCLE or MS_GROUP AUTHOR Charlie Gage COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. **************************************************************************** Documentation for avs module vbandcomb INPUT images An array of input images. image_num The number of input images. mapping_type Integer representing type of mapping to occur. cs_model Integer representing the color space model of the output image. OUTPUT newimage The resulting band combined image. DESCRIPTION vbandcomb combines all bands from m images (in separate files) into one image that contains all data bands. The input images are passed in as an array of pointers to xvim- age structures. There is no limit to the number of images that may be used as input to the routine. Each input image may be either a single band or multiband image with a map scheme of NONE, ONEPERBAND, or SHARED. The options for this program include, map option, and color space model. The map options (-m) corresponding to the integer mapping_type include, 0 - ignore maps 1 - map data through the maps 2 - transfer map information If the mapping_type option is set to 0, then the maps are ignored. That is, only the data from the input images are combined into a single multiband image. The resulting map scheme will be NONE. If the mapping_type option is set to 1, then the the data is mapped through the bands before combining the bands. If the map scheme for an input image is set to NONE, then that image is not mapped (ie. it has already been mapped). The resulting map scheme will be set to NONE. If the mapping_type option is set to 2, then the maps are transferred to the resulting multiband output image. If the map scheme for an input image is set to NONE, then a linear map is generated for that image. Input images with map schemes of ONEPERBAND and SHARED will have their maps transferred to the new multiband image. Note that if the maps are of different sizes, then the smaller maps will be expanded to the size of the largest map from all the input images. The resulting map scheme will be set to ONEPERBAND. The concatenation will be to tack the second image band to the bottom of the first image, and the third image band to the bottom of the second image band, etc. If the color space model (cs_model) option is set to some- thing other than NONE and the resulting image does not con- tain 3 bands, the color space model passed in will be over- ridden and set to NONE. The input to bandcomb: struct xvimage *images[] This is an array that will contain the pointers to all the images that need to be conbined. There is no limit on the number of images bands to combine. int image_num This is the number of pointers to images. The size of *images[]. int mapping_type This flag denotes whether or not to ignore the maps (mapping_type = 0), map the data through the maps (mapping_type = 1) before combining the bands, or to transfer the maps to the resulting image (mapping_type = 2). int cs_model This specifies the color space model of the resulting image. Where valid parameters for cs_model are 0 to 15: 0. None (default) 1. ntsc RGB 2. ntsc CMY 3. ntsc YIQ 4. HSV 5. HLS 6. IHS 7. cie RGB 8. cie XYZ 9. cie UVW 10. cie ucs UVW 11. cie ucs SOW 12. cie ucs Lab 13. cie ucs Luv 14. GENERIC 15. generic RGB vbandcomb will return a 1 upon success and a 0 upon failure. SEE ALSO vbandcomb(1), intro(3), vipl(3), verror(3), vutils(3) map- data(3) RESTRICTIONS If m_flag is set to 1 (map data through the maps) and all input images are not of type BYTE, bandcomb will fail. All of the input image data must be of the same storage type, otherwise bandcomb will fail. AUTHOR Tom Sauer, Mark Young COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ********************************************************************************* Documentation for avs module vbandspt1 INPUT 1. img1 -- input xvimage structure 2. img2 -- operation gating xvimage structure 3. mflg -- if set to one, use img2 to gate the sqrt operation The inputs must be of the same data type and size. OUTPUT 1. img1 -- output xvimage structure img1 is used for both the input xvimage structure and the output result xvimage structure. This is done to save space, but you must be careful not to overwrite important data. DESCRIPTION vbandspt1 extracts a specified data band from a multiband image and creates a new image containing only that band. The map is also carried along with the new image, the map scheme will become oneperband regardless of the input image's mpa scheme. The comment field of the new image will read the same as the comment field of the input image, except it is appended with the band number and the filename from which the band was taken. The arguments to vbandspt1 include : img the input xvimage structure to extract bands from images a list of pointers to xvimage structures. The result is passed in from a call to creat_images_list (image->num_data_bands). This argument is also used to return a list of pointers to xvimage structures, the new images containing only one data band are returned in this structure img_file_name a pointer to the name of the img file mod_comment this is a flag that if set to true modifies the new image's comment field by appending the data band number and the original file name from which the new image was created NOTE : band numbering begins with 0 The command, vbandspt1 -i ball.rgb.xv -o ball.b.xv -b 2 will extract the third band ( the band representing blue), from the 3 band rgb input image. The result is a 1 band image stored as ball.b.xv. SEE ALSO vbandspt3(3) AUTHOR Tom Sauer ********************************************************************************** Documentation for avs module vbandspt3 INPUT OUTPUT DESCRIPTION Extracts 3 bands from an image and creates new images containing only one band. The 3 bands extracted start with the band number. Specified by the -b option. The band numbering scheme starts at zero. The map is carried along with the new image, the map scheme will become ONEPERBAND regardless of the input image's map scheme. The comment field of the new image will read the same as the comment field of the input image, except it is append with the band number and the filename from which the band was taken. The output files are optional arguments, if all or any output files names are not specified, vbandspt3 will use the input filename with a suffix appended to it as the output filenames. The -b option determines which data band to extract. The default is 1. SEE ALSO intro(1), verror(3), vgparms(3), vutils(3) COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ********************************************************************************** Documentation for avs module vcast INPUT images array of pointers to xvimage structures image_num integer indicating the number of input images up_type optional target data type. Pass in "-1" to select auto upconvert. OUTPUT images array of pointers to resulting xvimage struc- tures. Return Value: 1 on success, 0 on failure. DESCRIPTION vcast will upconvert or upcast each input image to the highest input image data type. Optionally, the user may elect to upcast all images to a specified data type, as long as it is a data type that is equal to or greater than the highest data type of the input images. If the user tries to select a data type that is lower than the highest data type of the input images, an error message will be produced indi- cating that down casting is not allowed. There are no restrictions as to the input image data types. The data types can range from BIT to DOUBLE. The input images may contain any combination of sizes or number of data bands. All map information from each input image is transferred to the corresponding output image. Note that when converting from type BIT to BYTE, the output values will be 0 or 1. This is different from the results one would obtain using the defaults with vconvert. In try- ing to preserve the integrity of the data, vcast scales the data by 1. This routine calls convert to do the actual up convert/cast of the image data. The inputs to cast include: struct xvimage *images[] This is an array containing pointers to all of the images that are to be upcast. There is no limit on the number of images to convert. int image_num This is the number of pointers to images. That is, the size of *images[]. int up_type This is the optional target data type. The target data type is specified by passing in the integer represent- ing the desired VIFF data type. If auto upconvert is to be used, then passing in the value "-1" will default to finding the highest data type of the input images and upcasting the remaining images to this data type. vcast will return a 1 upon success and a 0 upon failure. SEE ALSO vcast(1), intro(3), vipl(3), verror(3), vutils(3) con- vert(3) AUTHOR Charlie Gage COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ************************************************************************************ Documentation for avs module vconvert INPUT image pointer to xvimage structure to be processed k VIFF data storage type to convert input image into sflg if non-zero then perform scaling using the scale_factor nflg if non-zero then perform normalization to norm_factor norm_factor value to normalize output image data to scale_factor value to scale image data by bflg logic switch to request each band be pro- cessed independently OUTPUT image receives the output image after processing Return Value 1 on success, 0 on failure. DESCRIPTION vconvert performs data storage type conversions from any VIFF type to any other, with the exception of the transform types. Scaling or (mutually exclusive) normalization can be performed if requested. The scaling and normalization options are important for controlling the loss of precision when converting from a higher data type to a lower data type. Output data storage type BYTE is a special case. If scaling is requested, then the input image is scaled, and then clipped to the range [0..255] before output. If normaliza- tion is requested, the data is offset adjusted and scaled to map onto the range [0..255] before output. Normalization for other output types simply scales the data so that the most positive data value is equal to the normal- ization target. No offset adjustment is performed. If the most positive value in the image is zero then a zero valued image of the desired data type will be produced. When converting from type BIT to type BYTE, the output values will be 0 or 255 depending on whether the bit corresponding to the input pixel is 0 or 1. For conversions from BIT to any type other than BYTE, the output value receives either 0 or 1 depending on the input bit value. This was done so that an BYTE image would be displayable immediately after conversion from type BIT. The nflg and sflg are used to indicate whether or not the image should be scaled or normalized. If the image is to be scaled or normalized, the norm_factor and scale_factor give the appropriate values. Note that img1 is used for both the input xvimage structure and the resulting output xvimage structure. This is done to save space, but you must be careful not to overwrite impor- tant data. Use of the bflg option is important when trying to normalize a multiband or vector image. If bflg is false then the larg- est value of any vector component in the image is used to compute the normalization multiplier. If bflg is true then a different normalization multiplier is used for each band, as dictated by the data in that band. SEE ALSO vconvert(1), intro(3), vipl(3), verror(3), vutils(3) scale(1), lvnormal(1) RESTRICTIONS There needs to be a way to specify the conversion from a COMPLEX type to a non-COMPLEX type to be either the real part or the magnitude (the current version does the real part only). AUTHOR Scott Wilson COPYRIGHT Copyright 1992, University of New Mexico. All rights reserved. ************************************************************************************ Documentation for avs module vctor INPUT image pointer to xvimage structure to be processed type specifies which type of conversion to use OUTPUT image holds the result of the convert operation. Return Value: 1 on success, 0 on failure. DESCRIPTION vctor performs simple mappings of COMPLEX data to REAL form. A COMPLEX image is transformed into a REAL image by one of four methods: 1 Assign the real part of the input to the output data. 2 Assign the imaginary part of the input to the output data. 3 Assign the magnitude of the input to the output data. 4 Assign the phase of the input to the output data. The output is the same type as the input (regarding single or double floats). Note that image is used for both the input xvimage structure and the resulting output xvimage structure. This is done to save space, but you must be careful not to overwrite impor- tant data. SEE ALSO vctor(1), intro(3), vipl(3), verror(3), vutils(3) rtoc(1),lvconvert(1) RESTRICTIONS Input images must be of type COMPLEX or DCOMPLEX. AUTHOR Scott Wilson COPYRIGHT Copyright 1992, University of New Mexico. All rights reserved. ************************************************************************************ Documentation for avs module vect2band INPUT *image pointer to the input/output xvimage structure OUTPUT *image pointer to the input/output (struct xvimage) DESCRIPTION vect2band rearranges the data stored in vector format to a file where each vector of the input file is represented as a single band in the output file. The number of pixels in each band of the output image is determined by the dimension of each vector (ie. number of bands) in the input image. The number of rows in the output image is set by the value of the subrow size of the input image. The number of columns in each band of the output image is found by divid- ing each input vector (pixel) by the subrow size. The number of bands in the output image is determined by the number of vectors (rows*cols) of the input file. For example, if an input file contained 5 vectors (pixels) of dimension 20 with a subrow size of 2, then the output file would contain a 5 band image with each band comprised of 2 rows and 10 columns. The data storage type of the output image will be of the same type as the input image. This routine will accept any data storage type, except BIT. The valid map schemes are NONE and SHARED. Map schemes of CYCLE and GROUP are not supported at this time. Note that a map scheme of GROUP may be appropriate for this transforma- tion, but is not yet defined. A map scheme of GROUP could be used to define a map for a pixel that is represented as a vector. Valid combinations of map scheme and map enable include: map scheme of SHARED with map enable of FORCE or OPTIONAL map scheme of NONE with map enable of OPTIONAL The map may be removed from an image by using "vremmap", or the data may be mapped through the map using "vmapdata" prior to using this routine. The argument, image represents the input/output viff image structure. SEE ALSO vect2band(1), intro(3), vipl(3), verror(3), vutils(3) dunload_vector(3), load_vector(3), vremmap(1), vmapdata(1), lband2vect(3). RESTRICTIONS Will not operate on VFF_TYP_BIT data files. Will not work with a map_scheme of ONEPERBAND, CYCLE, or GROUP. AUTHOR Charlie Gage COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ************************************************************************************ Documentation for the avs module vect2row INPUT *image pointer the input/output xvimage structure single_vect integer flag which, if set to 1, indicates that only on vector is to be extracted row_offset integer, if single_vect is set, this defines the row position of the targeted pixel col_offset integer, if single_vect is set, this defines the column position of the targeted pixel OUTPUT *image pointer to the input/output (struct xvimage) DESCRIPTION vect2row reformats data stored in vector (multi-band) for- mat to a single-band file where each vector is represented as a separate row in the output file. The number of rows in the resulting vector image will be the product of the origi- nal row and column sizes (ie., the total number of vectors), and the number of columns in the resulting image will be the vector dimension, or number of bands, found in the original file. If the flag "single_vect" is set to 1, only the pixel vector defined by [row_offset][col_offset] is extracted. In this case, the output header fields "startx" and "starty" are set to col_offset and row_offset to retain position information that might be needed in later processing of the output file. If the single_vect flag is not set, the entire data set is converted from vector format to the single-band row representation. In this case, the header field "subrow_size" in the output file is set to the original row_size value. This information can then be used for the inverse conver- sion, lrow2vect (not implemented yet). SEE ALSO vect2row(1), intro(3), vipl(3), verror(3), vutils(3) RESTRICTIONS Cannot operate on VFF_TYP_BIT. AUTHOR Donna Koechner COPYRIGHT Copyright 1991, University of New Mexico. All rights reserved. ************************************************************************************ Documentation for avs module vmos2band INPUT image pointer to input xvimage structure sub_rows num rows per subimage (including borders) sub_cols num cols per subimage (including borders) sub_border subimage border (inner border) size in pixels sub_x_off col index through subimages (1 img per index) sub_y_off row index through subimages (1 img per index) sub_skip skip value between subimages to be banded num_flag if set, user specifies num subimages banded num_subs number of subimages that will be banded OUTPUT img1 output banded image DESCRIPTION mos2band converts a mosaic input image to an output image in which each subimage of the input mosaic constitutes a band of the output image. The output image generated by mos2band, img1, will be (r- 2*bs) rows by (c-2*bs) columns with n bands, where r and c are the number of rows and columns per subimage, bs is the subimage border size, and n is the number of subimages that are to be put into band format. Lvmos2band assumes that all subimages are same size (r*c) and all subimages have the same border size (bs). Subimages from the input mosaic image (image) are assigned to bands in the multiband output image (img1) in the following manner: The first subimage specified is assigned to the first band in img1. Subsequent bands are assigned subsequent subimages indexed from left to right, top to bottom. Lvmos2band accepts VIFF data_types (excluding VFF_TYP_BIT) and returns that same data_type. If a map is associated with the input mosaic image, the same map will be assigned to the output multiband image. Number of columns and number of rows in subimages The subrows and subcols parameters are used to specify the number of rows and the number of columns, respecively, per subimage. Lvmos2band assumes that all subimages in the mosaic image are the same size. The sub_rows and sub_cols values SHOULD include any borders associated with the subim- ages. Subimage border size The sub_border parameter specifies the subimage border size in pixels. Again, this parameter will be applied to all subimages in the mosaic. When mos2band converts the mosaic image to a multiband image, the subimage borders will be removed from the subimages before storing them in bands. The size of the output image, img1, will therefore be (sub_rows-2*sub_border) rows by (sub_cols-2*sub_border) columns by n bands. Overall mosaic image border size The img_border parameter specifies, in pixels, the size of an outer border that should be removed from the mosaic image before extracting the subimages. The overall mosaic image border and the subimage borders are independent. Horizontal and vertical offset of first subimage to be banded The the first subimage in the mosaic that will be put into the multiband output image is specified by sub_x_off (hor- izontal offset) and sub_y_off (vertical offset). The speci- fied subimage will then be the first band in the output image. The indices, x and y, index through the subimages (they are NOT indices through the input mosaic image rows and columns). Therefore, if a mosaic image contained 9 4- row by 4-col subimages arranged as 3 subimages in the hor- izontal direction by 3 subimages in the vertical direction, the center subimage would be indexed by sub_x_offset=1, sub_y_offset=1 (not by sub_x_offset=4, sub_y_offset=4). Number of subimages to be put into band format Two parameters are passed to mos2band to indicate the number of subimages that should be put into band format, starting with the first subimage described by sub_x_offset and sub_y_offset. The num_flag is set if the user specifies the number of subimages option. In the case that num_flag is TRUE, the value passed in by num_subs is used. If the specified number of subimages cannot be extracted, mos2band will return an error and the output image will not be created. If num_flag is FALSE, mos2band calculates the number of subimages that will be banded, taking into account both the subimage skip value and the subimage offsets. Subimage skip value The subimage skip value parameter (sub_skip) specifies the number of subimages to be skipped each time a subimage is stored as a band. For example, a skip value of sub_skip=1 in a 3x3 subimage mosaic would band the subimages in a checkerboard pattern (every other subimage is a band in the output image). When applying the subimage skip value, mos2band looks at the series of subimages as a linear array. Therefore, the row/column arrangement of subimages does not affect how the skipping occurs. SEE ALSO vmos2band(1), intro(3), vipl(3), verror(3), vutils(3) RESTRICTIONS Vmos2band does not work on explicit location data and will return an error when such an image is encountered. No out- put image will be created. AUTHOR Donna Koechner COPYRIGHT Copyright 1992, University of New Mexico. All rights reserved. ************************************************************************************ Documentation for avs module vrect2pol INPUT *image (struct xvimage) data to be converted convert_dir (int) 0 = rectangular -> polar, 1 = polar to rect. process_dir (int) 0 = down vectors, 1 = across bands OUTPUT *image (struct xvimage) converted image DESCRIPTION rect2pol converts a data file from rectangular coordinates to polar coordinates and polar coordinates to rectangular coordinates. The data can be processed across bands or down vectors. 1) struct xvimage *image A pointer to the image to be converted. The data is overwritten with the converted data. 2) int process_dir The process direction of the data, 0 = down vec- tors, 1 = across bands. 3) int convert_dir The convertion direction, 0 = rectangular -> polar and 1 = polar to rectangular. rect2pol will return a 1 upon sucess and a 0 upon failure. SEE ALSO vrect2pol(1), intro(3), vipl(3), verror(3), vutils(3) RESTRICTIONS Data storage types of integer, float or complex are required AUTHOR Ramiro Jordan, Jeremy Worley, Tom Sauer COPYRIGHT Copyright 1992, University of New Mexico. All rights reserved. ************************************************************************************* Documentation dor avs module vrtoc INPUT image1 pointer to xvimage structure to be processed image2 optional pointer to second xvimage structure (leave NULL otherwise) type selects the type or REAL to COMPLEX conver- sion OUTPUT image1 receives the output xvimage structure Result Value: 1 on success, 0 on failure DESCRIPTION rtoc performs simple conversions of REAL data to COMPLEX form. A non-COMPLEX image is transformed into a COMPLEX image by one of four methods: 1 Move the first input image into the real part of the complex output image. If a second input image is present, then move it into the imaginary part - other- wise leave the imaginary part as zero. 2 Move the first input image into the imaginary part of the complex output image. If a second input image is present, then move it into the real part - otherwise leave the real part as zero. 3 Move the first input image into the magnitude part of the complex output image. If a second input image is present, then move it into the phase part - otherwise leave the phase part as zero. 4 Move the first input image into the phase part of the complex output image. If a second input image is present, then move it into the magnitude part - other- wise leave the magnitude part as one. Note that image1 is used for both the input xvimage struc- ture and the resulting output xvimage structure. This is done to save space, but you must be careful not to overwrite important data. SEE ALSO vrtoc(1), intro(3), vipl(3), verror(3), vutils(3) vctor(1),vconvert(1) RESTRICTIONS Input images must not be BIT, COMPLEX, or transform types, and must have no map. AUTHOR Scott Wilson COPYRIGHT Copyright 1992, University of New Mexico. All rights reserved. **************************************************************************************