Converting a binary Source File into ASCII

Also available in 简体中文

This article explains how to convert binary files used for the Source File object into ASCII text files. The text output is useful for investigating ray data present in the files. Once generated, the text output files can also be used for the Source File object. However, it is recommended that binary files are always for the Source File object whenever possible because ray tracing can be significantly slower when using a text file rather than a binary file to represent the ray data.

Authored By Sanjay Gangadhara

download example (.zip)

Introduction

The Source File object can be used to directly specify the coordinates, cosines, intensities, and wavelengths for a set of source rays in Non-Sequential mode. LEDs and other complex sources are most accurately modeled with the Source File object.

OpticStudio supports two formats for the Source File object: binary and ASCII. Binary allows large ray data sets to be stored in small files, and ASCII allows users to inspect the contents of the file. A file can be converted from binary to ASCII with a simple piece of C code. This code can be useful for interpreting the binary files used by the Source File object in OpticStudio, and for interpreting Ray Database (ZRD) files.

Source code for converting binary files to ASCII

The application (SourceFileRead.exe) which converts binary source files to ASCII text files is available in the zip file within the article attachments. Also located in that folder is the source code (SourceFileRead.c) used to generate the application.

The code is fairly simple. Structures are first defined which match those used to store the ray data in the binary file:

/* Define the data structure for the file header information */

typedef struct

{

int Identifier;         // Will be set to 8675309 or 1010 for 

//  quick check of proper format

int NbrRays;            // The number of rays in the file

char Description[100];  // A text description of the source

float SourceFlux;       // The total flux in watts of this 

//  source

float RaySetFlux;       // The flux in watts represented by

//  this Ray Set

float Wavelength;       // The wavelength in µm, 0 if

//  a composite

float AzimuthBeg, AzimuthEnd;  // Angular range for ray set

// (Degrees)

float PolarBeg, PolarEnd;      // Angular range for ray set

// (Degrees)

long DimensionUnits;    // METERS=0, INCHES=1, CM=2, FEET=3,

//  MM=4

float LocX, LocY,LocZ;  // Coordinate Translation of the source

float RotX,RotY,RotZ;   // Source rotation (Radians)

float ScaleX, ScaleY, ScaleZ;  // Scale factor to expand/

//  contract source

float unused1, unused2, unused3, unused4;

int reserved1, reserved2, reserved3, reserved4;

} NSC_RAY_DATA_HEADER;
 

/* Define the data structure for the ray information */

typedef struct

{

float x, y, z;

float l, m, n;

float intensity;

} FLUX_ONLY;


typedef struct

{

float x, y, z;

 float l, m, n;

float flux, wavelength;

} SPECTRAL_COLOR;

Note that different data structures are used for files that contain wavelength information for each ray (i.e. Spectral Data Format or .SDF files) and for files that do not contain wavelength information (i.e. .DAT files).

The main call to the code is then made, and variables are defined to store the ray data:

int main(void)

{

char filein[MAX_PATH_LENGTH];

char fileout[MAX_PATH_LENGTH];

char disp[MAX_PATH_LENGTH];

int i, file_ident, file_rays, file_format, file_type;

long file_dim;

float xr, yr, zr, lr, mr, nr, intr, wavr;

FILE *in, *out;

NSC_RAY_DATA_HEADER nscrdh;

FLUX_ONLY nscrdf;

SPECTRAL_COLOR nscrdc;

The user is then prompted to enter the names of the binary input file and the ASCII output file:

/* Determine the file names to be read from and written to */

printf("Enter the name of the binary file to be converted (include full path): ");

gets(filein);

printf("Enter the name for the ASCII text file (include full path): ");

gets(fileout);

Next, the input and output files are opened, so that they may be read from/written to, respectively (if the input file cannot be found, the program will terminate, and an error will be written to the ASCII output file). Header data present in the binary file is then read into local variables, to confirm that the input file has the proper format:

/* Read necessary header data into local variables &

confirm file format */

fread(&nscrdh,1,sizeof(NSC_RAY_DATA_HEADER),in);

file_ident = nscrdh.Identifier;

file_rays = nscrdh.NbrRays;

file_dim = nscrdh.DimensionUnits;

file_format = nscrdh.ray_format_type;

file_type = nscrdh.flux_type;


if ((file_ident == 1010) || (file_ident == 8675309))

{

sprintf(disp, "Valid file identifier \n");

fputs(disp, out);

}

else

{

sprintf(disp, "Incorrect file identifier");

fputs(disp, out);

 goto fast_exit;

}


if ((file_format == 0) || (file_format == 2))

{

if (file_format == 0)

{

if ((file_type == 0) || (file_type == 1))

{

goto data_write;

}

else

{

sprintf(disp, "Incorrect flux type identifier");

fputs(disp, out);

goto fast_exit;

}

}

else

{

if (file_type != 0)

{

sprintf(disp, "Incorrect flux type identifier");

fputs(disp, out);

goto, fast_exit;

}

}

}

else

{

sprintf(disp, "Incorrect file format identifier");

fputs(disp, out);

fputs("\n", out);

sprintf(disp, "File format identifier = %i", file_format);

fputs(disp, out);

goto fast_exit;

}

Finally, the header data are written to the output file, along with the coordinate, cosine, intensity and (optionally) wavelength data for each ray in the input file:

/* Write header, ray information into output file */

sprintf(disp, "%i %i \n", file_rays, file_dim, file_format, file_type);

fputs(disp, out);

if (file_format == 0)

{

for (i=0; i <= file_rays - 1; i++)

  {

fread(&nscrdf,1,sizeof(FLUX_ONLY),in);

xr = nscrdf.x;

yr = nscrdf.y;

zr = nscrdf.z;

lr = nscrdf.l;

mr = nscrdf.m;

nr = nscrdf.n;

intr = nscrdf.flux;

sprintf(disp, "%f %f %f %f %f %f %f \n",

xr, yr, zr, lr, mr, nr, intr);

fputs(disp, out);

}

}

else

{

for (i=0; i <= file_rays - 1; i++)

{

fread(&nscrdc,1,sizeof(SPECTRAL_COLOR),in);

xr = nscrdc.x;

yr = nscrdc.y;

zr = nscrdc.z;

lr = nscrdc.l;

mr = nscrdc.m;

nr = nscrdc.n;

intr = nscrdc.flux;

wavr = nscrdc.wavelength;

sprintf(disp, "%f %f %f %f %f %f %f %f \n",

xr, yr, zr, lr, mr, nr, intr, wavr);

fputs(disp, out);

}

}

The format of the output text file matches the ASCII file format for the Source File object, as described in the OpticStudio Help Files section, “NSC Sources”.

Application for converting binary files to ASCII

The application is started by double-clicking on the icon. This brings up a screen which prompts the user to provide the file name for the input binary file (.DAT):

As indicated in the prompt, the full path needs to be included. Once an input file has been provided, the user will be prompted to enter the desired file name for the ASCII output file (.txt):

Again, the full path needs to be included. Once the file name has been entered, the output file will be generated. This may take some time, depending on the size of the original input file. As indicated in the previous section, the format of the output text file matches the ASCII file format for the Source File object, as described in the chapter of the OpticStudio Help Files section entitled “NSC Sources”. Thus, this output file may also be used with the Source File object (although the header information in the file needs to be modified slightly, e.g. the name of the binary file is included in the header of the resulting ASCII text file but would have to be removed if this text file was to be used in OpticStudio). However, we always recommend that the binary file is used for ray tracing purposes, whenever possible, as use of the text file can be significantly slower.