READASCII [TOC]

by Ben-chin Cha (11/18/04)

INTRODUCTION


READASCII is a mouse driven IDL widget progranm, it provides a flexible user interface to allow a user to preview and extract any fixed format data from an ascii input file, and easily pass the extracted data array to IDL PLOT1D and PLOT2D subprograms.

The PLOT1D program is a general purpose single/multiple line plot package. The PLOT2D program is a general purpose 2D image displaying package. It provides various TV, SURFACE, and CONTOUR plot for 2D array. It allows the user dynamically reset the plot title, margins, surface plot viewing angles, X, Y labels, color scheme and generate the PostScript plot.

The high quality interactive plot pacakge of IDL 6.1 ITOOLS in PLOT1D and PLOT2D are also accessible through readascii package.

Command Syntax

Running IDL developer version, please refer User's Reference Guide for READASCII for command syntax.

A standalone IDLVM 6.1 license free version of readascii is accessible from readascii.sav



SYSTEM SETUP

Setup Requirement for Unix System

At APS all IDL programs are installed in the /usr/local/epics/extensions/idllib directory. For proper operation of these programs, a user first has to make sure that the IDL 6.1 or later is used. If IDL 6.1 to be used, set the following : 
 
	source /usr/local/rsi/idl_6.1/bin/idl_setup
In order to access IDL programs installed in the local epics/extensions/bin and epics/extensions/idllib, a user has to make sure that the following two environment variables are set before invoking IDL : 
         setenv EPICS_EXTENSIONS /usr/local/epics/extensions
         setenv IDL_STARTUP $EPICS_EXTENSIONS/idllib/viewer_startup.pro
and make sure the directory /usr/local/epics/extensions/bin/$EPICS_HOST_ARCH is in his/her program search path.

Access READASCII Program

Following example shows how to run IDL and READASCII window application on UNIX system. To access the READASCII program in IDL just enter the wd_readascii command at the IDL prompt: 
	idl
	IDL> wd_readascii
This commnad will automatically load the wd_readascii.pro and other appropriate prgrams at runtime.

Access License Free READASCII Program

If the readascii.sav installed on the epics/extensions/bin/$EPICS_HOST_ARCH, a user can access the license free version by using the UNIX script idlvm 
	idlvm readascii
If above method failed, a user has to download the readascii.sav first. Make sure IDL 6.1 is the default version for your system, then try the following method. 
	idl -vm=/full-dir-path/readascii.sav
where /full-dir-path/ specifies where the readascii.sav resides.

USER INTERFACE

The WD_READASCII program allows the user freely to select the fixed format data file and provide text preview and controls of array selection. The main user interface window is given below.

WD_READASCII

File           Pop up file selection dialog with default type '*txt*' or '*im*'

Filname Field  Display filename currently selected 

ASCII...       Pop up a scroll window display the content in filename

1D/2D Droplist Set X,Y line numbers according to 1D/2D data

Close          Exit WD_READASCII program

Data Control Fields

	Y Axis Line #    Specify line seq number which contains Y values
	Data Start Line  Specify data start line seq number 
	Total Data Lines Specify totol lines to be read, leave blank for all
	Comment Char     Specify comment character for ignored line
	X Axis Column #    Specify column seq number which contains X values
	Data Start Column  Specify data start column seq number 
	Total Data Columns Specify totol columns to be read, leave blank for all

Accept         Accept control field values and append array table

Transpose      Transpose table columns and rows

PLOT1D...      Plot selected columns or rows

PLOT2D...      Plot table as 2D image array

HELP...        Display online help

Step#/Values   1D/2D plot axis use step # or real values

ASCII...WINDOW

The 'ASCII...' button pops up the following window. This window displays the text data from the selected fixed format input file. Both the column and line sequence number are zero based. 
 As shown in this text window:
	the lines start with ';' at column 1 treat as comment
	the 4th line (i.e. seq # 3) contains the Y values, 
	the 1st column (i.e. seq # 0) contains the X values, 
	the data array starts from 8th (i.e. seq # 7) line and 3rd (i.e. seq # 2) column.
As shown in above main window, the column and row controls fields must reflect the actual zero based data seq # in the text file.

EXTACTED ARRAY

The 'Accept' button accepts the column and row fields specification then extracts data array from the text file and creates/populates the 2D array table. The following window shows the result from the 'Accept' button. Since no total columns and lines are specified, therefore the whole data array are read in. And the 'PlOT1D...', 'PLOT2D...', 'Transpose' buttons become active after data table been polulated.

PLOT2D WINDOW

This window shows the 'PLOT2D...' button result which plots the extracted table array as a 2D image.

SELECTED ARRAY

By default all columns will be selected by PLOT1D. A user can pick any column or row number from the array table, the selected column or row will be highlighted. The 'PLOT1D...' button will accept the highlighted data and passed to PLOT1D program. This window shows the columns selected from the extracted table array.

PLOT1D WINDOW

This window shows the 'PLOT1D...' button result which plots the selected columns from the above table array.