The Parser for the Wyko Vision ASCII File Format

Summary

The parser is implemented in Matlab by virtue of its convenient variable save-load mechanism so that we can selectively retrieve variables that we need without losing any data at the same time.
The current version is 2.0 beta.
The source code files are available at:

The main function is mitac_ascii_parser_main(), while the other three are subroutines.

See Basic Usage to have a quick view on how to use the parser in a custom Matlab script.
See Implementation Detail for the assumptions and a few known problems of the file format and our strategies.
See Function Specification for the detail of the functions.
See Todo for the future plan of improvement.

Also see The Wyko Vision ASCII data format for a better understanding of the parser.

Basic Usage

[s_path_channelAB, s_path_profile_z, s_path_intensity, s_path_head] = mitac_ascii_parser_main(s_path_in, s_dir_out)

where

s_path_in: the path string for the input ASCII file
s_dir_out: the path string for the output folder, in which all generated Matlab MAT data files will be saved.
s_path_channelAB: the path string for the output Matlab MAT data file that contains an unknown data array in the header of the complete ASCII format.
s_path_profile_z: the path string for the output Matlab MAT data file that contains the z-profile data matrix and the bad data registry.
s_path_intensity: the path string for the output Matlab MAT data file that contains the intensity data matrix and the bad data registry.
s_path_head: the path string for the output Matlab MAT data file that contains the header variables.

The variables to be retrieved in client code:

vc_channelAB_val: a column vector that contains all the channelAB data in the file header, in the same linear order of the original data.
m_profile_z: a 2D matrix that contains the z-profile data array. The rows and columns correspond to the y and x dimension respectively. In a raw file, bad data can exist and a bad data is denoted as NaN.
mr_i_profile_z_bad_run: a n2 matrix as a registry for bad data runs in the z-profile matrix. Each row represents a 2-element location tuple (starting index and number of elements) for a bad data run in the z-profile matrix.
m_intensity: a 2D matrix that contains the intensity data array. The rows and columns correspond to the y and x dimension respectively. In a raw file, bad data can exist and a bad data is denoted as NaN.
mr_i_intesity_bad_run: a n
2 matrix as a registry for bad data runs in the intensity matrix. Each row represents a 2-element location tuple (starting index and number of elements) for a bad data run in the intensity matrix.
See The Wyko Vision ASCII data format for a detailed header variable list. It can also be found in Line 33 - 100 of the source code _mitac_ascii_parsermain.m.

See Function Specification for details. Also see Matlab Function Reference [5] for how to load a Matlab MAT data file.

Implementation Detail

Function Specification

mitac_ascii_parser_main

Main function of the parser.

Syntax

[s_path_channelAB, s_path_profile_z, s_path_intensity, s_path_head] = mitac_ascii_parser_main(s_path_in, s_dir_out)

Description

Parameters

s_path_in: the path string for the input ASCII file.
s_dir_out: the path string for the output folder, in which all generated Matlab MAT data files will be saved.
s_path_channelAB: the path string for the output Matlab MAT data file that contains an unknown data array in the header of the complete ASCII format.
s_path_profile_z: the path string for the output Matlab MAT data file that contains the z-profile data matrix and the bad data registry.
s_path_intensity: the path string for the output Matlab MAT data file that contains the intensity data matrix and the bad data registry.
s_path_head: the path string for the output Matlab MAT data file that contains the header variables.

The variables to be retrieved in client code:

vc_channelAB_val: a column vector that contains all the channelAB data in the file header, in the same linear order of the original data.
m_profile_z: a 2D matrix that contains the z-profile data array. The rows and columns correspond to the y and x dimension respectively. In a raw file, bad data can exist and a bad data is denoted as NaN.
mr_i_profile_z_bad_run: a n2 matrix as a registry for bad data runs in the z-profile matrix. Each row represents a 2-element location tuple (starting index and number of elements) for a bad data run in the z-profile matrix.
m_intensity: a 2D matrix that contains the intensity data array. The rows and columns correspond to the y and x dimension respectively. In a raw file, bad data can exist and a bad data is denoted as NaN.
mr_i_intesity_bad_run: a n
2 matrix as a registry for bad data runs in the intensity matrix. Each row represents a 2-element location tuple (starting index and number of elements) for a bad data run in the intensity matrix.
See The Wyko Vision ASCII data format for a detailed header variable list. It can also be found in Line 33 - 100 of the source code _mitac_ascii_parsermain.m.

Remarks
The function calls _mitac_ascii_parser_securereadline(), _mitac_ascii_parser_get_leftmostfield(), and _mitac_ascii_parser_get_rightmostfield().

mitac_ascii_parser_secure_readline

Sometimes after calling the Matlab function textscan() with a customized format string, fid could stay in the same line, this is a handler to ensure the fid points to the next line.

Syntax

[s1] = mitac_ascii_parser_secure_readline(fid, b_init)

Description

fid: read pointer passed from the Matlab function fopen()
b_init: boolean for whether to read an additional line.
s1: the string of current line.

mitac_ascii_parser_get_leftmost_field

Get the leftmost field of a line, typically this is the field name.
Syntax

[s] = mitac_ascii_parser_get_leftmost_field(s1)

Description

s1: The returned string from _mitac_ascii_parser_securereadline
s: the leftmost field of the current line, typically the title of the data block.

Remarks
The delimiter is assumed to be comma.

mitac_ascii_parser_get_rightmost_field

Get the rightmost field of a line, typically this is the field name.

Syntax

[s] = mitac_ascii_parser_get_rightmost_field(s1)

Description

s1: The returned string from _mitac_ascii_parser_securereadline
s: the rightmost field of the current line, typically the value of the data block.

Remarks
The delimiter is assumed to be comma.

Todo