6.7.28 SaveVectorFrames

6.7.28.1 Outline of the node

Saves data of frames in the Vector<ObjectRef>  type in a file. Note that the supported ObjectRef are the float type and the complex<float> type only.

6.7.28.2 Necessary file

No files are required.

6.7.28.3 Usage

When to use

This node is used to save data stored in the Vector<ObjectRef> type for multiple frames in one file.

Typical connection

Figure 6.137 shows a connection example using SaveVectorFrames in a network. In this network, SaveVectorFrames takes data outputted in the SPECTRUM terminal, the hidden output of LocalizeMUSIC , as the input. The data is power of the MUSIC spectrum for every direction. For future use or for documentation, SaveVectorFrames can be used to save the data in a file. For more information on LocalizeMUSIC hidden output SPECTRUM, see LocalizeMUSIC Node Reference, specifically LocalizeMUSIC ’s 6.2.14.4 Input-output and property of the node.

\includegraphics[width=.8\textwidth ]{fig/modules/SaveVectorFrames}
Figure 6.137: Connection example of SaveVectorFrames 

6.7.28.4 Input-output and property of node

Input

INPUT

: Data of frames in the Vector<ObjectRef> type. The supported types are the Vector<float> type and the Vector<complex<float> > type.

Output

OUTPUT

: A file in which data in the Vector<ObjectRef> type for multiple frames were saved.

Parameter

Table 6.132: Parameter list of SaveVectorFrames 

Parameter name

Type

Default value

Unit

Description

FILENAME

string 

   

The file name of the output file.

OUTPUTTYPE

string 

TEXT

 

The file format options for the output file. Select TEXT for a text file or RAW for a binary file.

FILENAME

: string  type. The file name for the output file.

OUTPUTTYPE

: string  type. The file format options for the output file. Select TEXT for text files or RAW for binary files. The default value is TEXT.

6.7.28.5 Details of the node

SaveVectorFrames takes data in either the Vector< float > type or the Vector<complex<float> > type for multiple frames as the input and then saves all data in one file. The file format is to be specified in the OUTPUTTYPE parameter. When the OUTPUTTYPE parameter is set to RAW, data of frames will be written in IEEE 754 32-bit single-precision floating-point number format by little- endian order. The default value of this parameter, TEXT, will output human-readable data unlike RAW.

Table 6.133 shows the details of how data will be formatted in the file when TEXT is selected in the OUTPUTTYPE parameter. Each data is separated by space and the data of frames are separated per frame in the Vector size by a line feed.

Table 6.133: File Format for TEXT OUTPUTTYPE

Datatype

File Format

Float

data[0] data[1] data[2] ... data[n]

 
 

data[0] data[1] data[2] ...... data[n]

 

Complex

data[0].real() data[0].imag() data[1].real() data[1].imag() ... data[n].real() data[n].imag()

 

float

   

Where n is based on the Vector size of the input data.

SaveVectorFrames checks the size of the Vector when it receives the data. In the sample network above (Figure 6.137), LocalizeMUSIC outputs Vector< float > . When the transfer function specified in the LocalizeMUSIC generated from 72 sound sources, the expected vector size will be 72. A transfer function is a model of sound propagation. The number of sound sources of a transfer function is one of the factors that affects the vector size and it is decided during transfer function creation. For more information on transfer function, please see a video on "HARK Transfer Function Tutorial" at https://www.hark.jp/document/harktv/. The detailed documents for generating Transfer Function can be found at https://www.hark.jp/document/transfer-function-generation-manuals/ as well.

Suppose the input data were stored in the Vector<float> type where the column size is 72 and there are 6397 frames in total, the contents of the output data file will be like one shown in Figure 6.138. It is assumed that the data were saved in the TEXT file format described in the Table 6.133.

\includegraphics[width=.8\textwidth ]{fig/modules/SaveVectorFrames-2}
Figure 6.138: Sample SaveVectorFrames Output File Content for TEXT Float Type

Note that the Frame numbers written on the left side of Figure 6.138 and Figure 6.139 are not written in the files.

Figure 6.139 gives sample contents of the output file when the input data were in the Vector<complex<float> > type like ones in the sample network given by Figure 6.137. The column size is 71 for each frame. There are 6397 frames in total. It is also assumed that the data were saved in the TEXT file format described in the Table 6.133.

\includegraphics[width=.8\textwidth ]{fig/modules/SaveVectorFrames-3}
Figure 6.139: Sample SaveVectorFrames Output File Content for TEXT Complex Float Type

Filename:

An option to use a special pattern, {tag:format}, with the data properties as known as a format string is available when specifying the value in the FILENAME parameter. The format string allows the users to set a filename which contains the information of the input data and so convenient for the later use.
The available tags are listed in the Table 6.134.

Table 6.134: Tag list of SaveVectorFrames 

Tag

Description

Unit

datatype

Data Type (float or complex float)

String

colsize

Column size of Vector

Integer

dim

Data Dimension (Fixed value. 1 for Vector)

Integer

The examples of the format string and the output are given in the Table 6.135.

Table 6.135: Examples of the format string and the output for Vector<complex<float> > where the Vector size is 20.

Format String (Parameter FILENAME value)

Output (Formatted Filename)

samplefile.dat

samplefile.dat

samplefile_{datatype}.txt

samplefile_complex_float.txt

samplefile_col{colsize}.raw

samplefile_col20.raw

samplefile_dim{dim}.dat

samplefile_dim1.dat

samplefile_{datatype}_col{colsize}_dim{dim}.dat

samplefile_complex_float_col20_dim1.dat

It is required to specify the column size and the data type in parameters when using LoadVectorFrames to load a file outputted by SaveVectorFrames into the Vector<ObjectRef> type. Hence, having data information in the filename will be useful for the later use.

As indicated in the Table 6.135, there is no rules on the file name extension. It can be any as user specify. It allows to have no file name extensions as well.

The value for "format" in {tag:format} is optional. The "format" can be used to specify the number of digits, for instance, 03d where the format specifiers are the same as the ones of printf in C.