Document Actions
Structured Picture File Command Format
Structured Picture File Command Format
Before creating your picture file, there are a few concepts you need to understand:
Contents of a Picture File
A picture file contains a series of commands. Each command consists of from one to four logical records. Each logical record corresponds to a FORTRAN READ/WRITE statement. In a formatted picture file, each logical record consists of one or more physical file records (lines). In a binary picture file, each logical record consists of exactly one physical record.
The first logical record of a picture file command contains five integer values. This record uses Format (5I5). The words of the control record are:
The control record is followed by data records with the integer, real, and character data. The data records, in order of appearance are:
The integer data record is only present if the number of integer data items is greater than zero. There can be up to 200 integer data items in the record.
The real data record is only present if the number of real data items is greater than zero. There can be up to 600 real data items in the record.
The character data record is only present if the number of characters is greater than zero. There can be up to 80 characters in the record.
Note: For binary files: picture file character data are stored as integer arrays with two characters in each integer array element.
In a formatted picture file, the integer and real data records may span many text lines. The standard rules of FORTRAN I/O provide for automatic line wrap. Always read/write the integer and real data records with a single statement.
In summary the first record of a picture file command is always five integers. This record gives the lengths of the other three records. If the length of a record is zero, it is not placed in the picture file. A picture file command consists of a single record if all the data item lengths are zero. The following is a sample subroutine.
SUBROUTINE PFREAD( LUN, CMDCLS, CMDNUM, NUMIN, NUMRL, NUMCH, $ INBUF, RLBUF, CHBUF, RDCND ) C PFREAD-SAMPLE MODULE - READ A PICTURE FILE COMMAND C PFREAD-13-DEC-1992 SDRC C C ****************************************************** C ***** COPYRIGHT (C) 1993 ***** C ***** BY STRUCTURAL DYNAMICS RESEARCH CORP. ***** C ***** ALL RIGHTS RESERVED ***** C ****************************************************** C C DESCRIPTION C C SAMPLE ROUTINE TO READ A FORMATTED PICTURE FILE COMMAND. C C THE CODE FOR A BINARY PICTURE FILE WOULD BE VERY SIMILAR, C JUST TAKE THE FORMATS OUT OF THE READ STATEMENTS. C C ACCESS C C CALL PFREAD( LUN, CMDCLS, CMDNUM, NUMIN, NUMRL, NUMCHR, C INBUF, RLBUF, CHBUF, RDCND ) C C INPUT VARIABLES C C LUN INTEGER VARIABLE C LOGICAL UNIT ON WHICH FILE IS OPENED. C FILE MUST BE OPENED FOR THE CORRECT TYPE OF C ACCESS. C C OUTPUT VARIABLES C C CMDCLS INTEGER VARIABLE C CLASS OF THE PICTURE FILE COMMAND. C C CMDNUM INTEGER VARIABLE C NUMBER WITHIN CLASS FOR THE PICTURE FILL C COMMAND. C CMDCLS AND CMDNUM TAKEN TOGETHER IDENTIFY THE C PICTURE FILE COMMAND. C C NUMIN INTEGER VARIABLE C NUMBER OF INTEGER DATA ITEMS IN THE COMMAND. C C NUMRL INTEGER VARIABLE C NUMBER OF REAL DATA ITEMS IN THE COMMAND. C C NUMCH INTEGER VARIABLE C NUMBER OF CHARACTERS IN THE COMMAND. C C INBUF INTEGER ARRAY (200) C INTEGER DATA ITEMS IN THE COMMAND. C C RLBUF REAL ARRAY (600) C REAL DATA ITEMS IN THE COMMAND. C C CHBUF INTEGER ARRAY (40) C CHARACTER DATA ITEMS IN THE COMMAND, STORED 2 C SYSTEM C CHARACTERS IN EACH INTEGER WORD. STORED C COMPATIBLE WITH FORTRAN 66 HOLLERITH CONVENTION: C DATA I / 2HAB / C C RDCND INTEGER VARIABLE C CONDITION FROM READ: C = 0 - NORMAL READ C = 1 - END OF FILE FOUND C = 2 - READ ERROR C C ERROR CONDITIONS C C ERRORS FOUND DURING THE READ ARE INDICATED TO THE CALLER C THROUGH RDCND. C C PROGRAMMER COMMENTS C C NOTICE USE OF FORTRAN 66 TECHNIQUES FOR CHARACTER C HANDLING. THIS OBSOLETE METHOD IS USED FOR COMPATIBILITY C WITH OLDER I-DEAS CODE. WHEN READING FROM A FORMATTED C FILE YOU COULD USE THE CHARACTER DATA TYPE INSTEAD. C C WITH A BINARY PICTURE FILE YOU MUST USE THE C FORTRAN 66 2 CHARACTERS/WORD METHOD. C C THIS ROUTINE HANDLES EVERYTHING BUT RASTER DATA.RASTER C DATA USES A SPECIAL FORMAT. C C HISTORY C C NONE C C EXTERNAL REFERENCES C C NONE C C VARIABLE DESCRIPTIONS C C LOCAL VARIABLES C C I LOOP INDEX FOR READ STATEMENT IMPLIED DO. C NWRD NUMBER OF WORDS TO READ FOR CHARACTER STRING. C C GLOBALS REFERENCED C C NONE C
C -------------------------------------------------------- C C CALL REAL RLBUF(600) INTEGER CHBUF (40), CMDCLS, CMDNUM, INBUF ( 200), LUN, NUMCH, NUMIN INTEGER NUMRL, RDCND C C LOCAL INTEGER NWRD, I C C PROGRAM START C --------------------------------------------------------- C C READ THE COMMAND HEADER C RDCND = 0 READ( LUN, 8001, END=6001, ERR=6002 ) CMDCLS, CMDNUM, $ NUMIN, NUMRL, NUMCH C C GET INTEGER DATA IF ANY. C IF( NUMIN .GT. 0 ) THEN READ( LUN, 8002, END=6001, ERR=6002 ) $ ( INBUF(I), I = 1 , NUMIN ) END IF C C GET REAL DATA IF ANY. C IF( NUMRL .GT. 0 ) THEN READ( LUN, 8003, END=6001, ERR=6002 ) $ ( RLBUF(I), I = 1 , NUMRL ) END IF C C GET CHARACTER DATA IF ANY C IF( NUMCH .GT. 0 ) THEN C C CONVERT NUMBER OF CHARACTER TO THE NUMBER OF WORDS C REQUIRED TO STORE THEM. C NWRD = ( NUMCH + 1 ) / 2 READ( LUN, 8004, END=6001, ERR=6002 ) $ ( CHBUF(I), I = 1 , NWRD ) END IF GOTO 9999 C C EXCEPTION: END OF FILE FOUND C 6001 RDCND = 1 GOTO 9999 C C EXCEPTION: ERROR ON READ C 6002 RDCND = 2 C 9999 RETURN C C FORMAT DEFINITIONS C 8001 FORMAT( 5I5 ) 8002 FORMAT( 5I15 ) 8003 FORMAT( 5E15.5 ) 8004 FORMAT( 40A2 ) END
Raster Data
Raster data is an exception to the normal picture file format rules. Special formats are used to store raster data because it is so voluminous. The details of raster data storage depend on the file type:
The red, green, and blue fraction for each pixel is stored as an integer in the range 0 to 255. The format is (24I3). This format fits 8 pixels on each file line. All the pixel data associated with a command is accessed with a single READ/WRITE statement. The FORTRAN I/O system handles the line wrap.
In the binary format one word is stored for each pixel. The RGB color value for a pixel is packed:
Bits
16:23 - Red component value (0 to 255)
8:15 - Green
0: 7 - Blue
All pixel data associated with a command is accessed with a single READ/WRITE statement.
Raster data is always stored immediately after the picture file command, DEFINE RASTER DATA. The number of pixels specified in the DEFINE RASTER DATA command controls the length of the raster data record.
Coordinate Systems
Two coordinate systems are used to specify data in the picture file:
Normalized Device Coordinates cover the entire display area. The NDC origin is at the bottom left-hand corner of the display area. The longest side of the display area has an NDC value of 1.0 and the other side is scaled uniformly.
Directed Raster Coordinates cover the entire display area. The DRC origin is at the bottom left-hand corner of the display area. DRC units are pixel oriented, so the maximum value depends on the display device for which the picture file was generated. The highest DRC resolution which the I-DEAS software can read is 2047 x 2047.
Color Information
Whenever a color attribute is specified in the picture file, it is defined in two ways:
Application Color Index - the number associated with the color in the I-DEAS color table. There are some predefined values: -2 is black and -1 is white.
RGB Value - the three real numbers specifying the red, green, and blue fraction which compose the color.
When a picture file is played back, the RGB values are used to define color. The application color indexes are unique to each I-DEAS model file, so they are not portable. The application color numbers are provided so you can do special processing based on the color numbers you assign.
Ordering Restrictions
Following is a list of rules regarding the order of records in a picture file.
For the rest of the rules discussion, assume that the application information commands do not exist. So if we say a command is the first in the picture file, that means that it is the first non-comment command in the picture file.
The first command in the picture file is DISPLAY INFORMATION. The next command is SOURCE DEVICE INFORMATION. Following these two commands are the VIEWPORT DEFINITION commands, one for each viewport.
This fixed order command sequence appears first in the picture file. The DISPLAY INFORMATION, SOURCE DEVICE INFORMATION, and VIEWPORT DEFINITION commands are used only in the fixed order sequence at the beginning of the picture file.
- All the attributes which apply to a primitive are defined before the primitive command. Note that the INITIALIZE ATTRIBUTES command defines the value of all graphic attributes.
- Raster data commands are bracketed by BEGIN and END RASTER LINE commands. The BEGIN and END RASTER LINE commands are only used as matched pairs.
- The FILL BACKGROUND commands are bracketed by BEGIN and END FRAME commands. The BEGIN and END FRAME commands are only used as matched pairs.
- The BEGIN and END FRAME commands are bracketed by BEGIN and END (or ABORT) ANIMATION commands. The BEGIN ANIMATION command always starts an animation bracket. An animation bracket can be ended by either an END ANIMATION command or an ABORT ANIMATION command.
If the animation bracket is terminated by an END ANIMATION command, then the proper number of frames must have been defined. If the animation bracket is terminated by an ABORT ANIMATION command, any number of frames may have been defined.
There is only one animation in each picture file.
- The END OF PICTURE FILE command should be the last command in the picture file. If omitted, the physical end of the file also terminates a picture file.
Following is a summary of the ordering rules:
Free Usage: Application Information
Fixed Order:
Required Sequence:
Set Graphic Context before any primitive
Set Clip Port before any text or marker primitive
All attributes which affect a primitive must be defined before the
Raster Restrictions:
Animation Restrictions: