Pictures represent rectangular areas on a display. The pictures have default coordinate systems that are linear and increase left to right and bottom to top, corresponding to GKS rules. Each picture can optionally have an associated transformation to allow for other coordinate systems. Pictures are stored in the database in the order they were created, so when recalling the last picture of a given name, for example, the most recently created picture of that name will be recovered.
The AGI interface to each graphics package will interpret the meaning of a picture to suit the design of that particular package. When used in conjunction with SGS a picture is made equivalent to an SGS zone. For example to save an SGS zone as a picture use
CALL AGS_SZONE( PNAME, COMENT, PICID, STATUS )
PNAME and COMENT are used to identify the picture in the database as described in the sections below. PICID returns the identifier for the new picture in the database.
There is one routine, AGI_NUPIC, that allows new pictures to be created in the database without necessarily opening a graphics package first.
WX1, WX2, WY1, WY2 define the rectangular extent of the new picture in terms of the world coordinates of the current picture. PNAME and COMENT describe the picture as discussed in the following sections. NEWX1, NEWX2, NEWY1, NEWY2 specify the world coordinate system of the new picture. PICID returns the identifier for the new picture in the database.
AGI works with a current picture in an analogous manner to SGS and its current zone. A new picture has to be created within the bounds of the current one, and this then becomes the current picture. Pictures are recalled from the database only if they lie within the physical bounds of the current one; the recalled picture then becomes the current one. A picture can be made current by calling the routine AGI_SELP.
The picture recall routines, AGI_RC*, provide the means of traversing the database. The key to the search is the picture name, and the search ends when a picture of the given name is found that lies within completely the bounds of the current picture. This picture then becomes the current picture. If no suitable picture is found then an error status is returned. The search can be made more general by giving an empty name string. This results in the first picture on the search path, that lies within the current one, being recalled. AGI_RCL searches backwards from the last (most recent) picture in the database. AGI_RCF searches forwards from the first (most ancient) picture in the database. AGI_RCP searches backwards starting at the picture given by the PSTART identifier, and AGI_RCS does the same searching forwards.
A further restriction on the search can be introduced by using the AGI_RC*P routines. With these, a picture is only recalled if it corresponds to the given name, lies within the bounds of the current picture, and encompasses a given point in the world coordinate space of the current picture. This type of recall is useful when a cursor has been put up on the display, and the user asked to select a picture with the cursor.
A potential problem arises when searching backwards through the database. The hierarchy of pictures in the database implies that previous pictures will usually be larger than the current one, but the search strategy requires the current picture to be larger than the picture being sought. This problem can be overcome by selecting a picture known to be larger than any picture being sought as the current one. The base picture is the most convenient as this is larger than any picture in the database. The following example shows how to search backwards through the database for a picture with a particular label (labels are discussed in Section 5.6).
For devices that allow the memories to be scrolled independently there is a potential conflict when searching for a picture. This occurs because under normal conditions a picture can only be recalled from the database if it lies within the current picture. If the pictures are located on different memory planes then this can be negated by scrolling one of the memories. To overcome this a more general search is allowed by selecting the root picture which contains all other pictures (including the base picture). A call to the routine AGI_SROOT selects the root picture. A subsequent call to any of the recall routines AGI_RC* will obtain the relevant picture without it having to lie within the current picture. The root picture is deselected in the recall routine, and so AGI_SROOT has to be called on every occasion that an unlimited search is to be made. Recall is the only operation allowed with the root picture. Any other operation called while the root picture is selected will result in the previously current picture being used.
When AGI needs to access information in the database by position it uses the world coordinate system of the current picture. World coordinates are those set up by the user to represent a useful linear range of coordinates which fill the picture space. These world coordinates must be linear and increase from left to right and from bottom to top. If the required coordinate system does not correspond to these rules then the user should choose a basic world coordinate system that does obey them, and then define a transformation to go to and from the basic system and the required one (see the section on transformations 5.8).
When a picture is created with one of the package interface routines the current world coordinates of the graphics zone are stored in the database. If the user subsequently changes the world coordinate system of the graphics space on the physical device, errors may result if information is requested from the database by position. The routine AGI_IWOCO can be used to inquire the world coordinates of the current picture.
The name is a character string indicating the type of picture created. It should reflect the general intention of the plotting space, and not describe specifically what the picture contains. For example, the name ‘FRAME’ is used to indicate that the space will be used to group together a collection of other plots. The name ‘DATA’ is used to indicate that the space will contain some sort of representation of data in graphical form, e.g. a grey-scale image, or a scatter plot. The name ‘BASE’ is used by AGI to signify the base picture, and this name should not be used for other purposes. The length of the name string is limited to the number of characters defined by the AGI__SZNAM constant from the AGI_PAR FORTRAN include file (currently 15 characters). When stored in the database the character string will have leading blanks removed and converted into upper case.
There are at present no compulsory names, but clearly consistent usage is necessary if packages written by different programmers are to integrate successfully.
The comment is a character string containing a description of the picture. The application can use this component to store any text that will help identify the picture in the database. It is restricted to one line of text at present, with a maximum length given by the parameter AGI__CMAX defined in the AGI_PAR include file. The comment string is stored with the picture at the time of picture creation.
There is another character identifier that can be stored in the database and used to distinguish a picture more precisely. This is the label which is an optional component of a picture. It differs from other structures in AGI in that its contents can be changed at any time (by overwriting the existing contents), whereas other picture elements can only be defined when they are first created. Because the label contents can be changed at any time the responsibility for guarding against misuse is left up to the application/user.
The labels differ in another way from the name component in that each label within a workstation structure must be unique. If a new label clashes with an exiting one within a workstation structure then the existing label will be deleted and replaced by a blank string. Although the labels are stored with mixed case the comparison is done with leading blanks removed and in uppercase only.
The routine AGI_SLAB will associate a label with an existing picture, indicated by the picture identifier. If the picture identifier is negative then the current picture is used to store the label. If a label already exists for a picture then the old one will be overwritten. The routine AGI_ILAB will return the label of the requested picture. If the picture identifier is negative then the current picture is searched. If no label is associated with this picture then a blank string is returned.
The length of the label string is limited to the number of characters defined by the AGI__SZLAB constant from the AGI_PAR include file (currently 15 characters).
It may often be desirable to access the data used by one application in a second one. To store the actual data in the database would be wasteful of disk space since this data would be replicated in the original data file and in the database. Even more space would be wasted if the same data was associated with more than one picture in the database. Instead of saving the data in the database AGI stores a reference to it (a string describing it’s location) that enables other applications to recover the data.
A reference to a data object is not a compulsory component of a database picture, and as such will not be created when a new picture is inserted in the database. An explicit call to one of the appropriate routines is used to create or access a reference object in the database. The subroutine argument that defines the reference object can be either an HDS locator or any character string reference. If the string is a valid HDS locator then a reference is constructed to point to the relevant object, otherwise the string is assumed to be a reference itself and is stored as supplied. This dual definition of what defines a reference is intended to smooth the transition from applications using raw HDS calls to using NDF routines to access the data. When the NDF reference mechanism is well established the HDS interface will be removed.
A reference is saved in the database by calling the routine AGI_PTREF. The reference structure is stored within the picture indicated by the picture identifier. If the picture identifier is negative then the current picture is used to store the reference. If a reference already exists in the picture then an error status will be returned.
A reference is obtained from the database by calling the routine AGI_GTREF. The reference is obtained from the picture indicated by the picture identifier. If the picture identifier is negative then the current picture is used to obtain the reference. If the reference was created from an HDS locator then an HDS locator is returned and this should be annulled in the application using REF_ANNUL rather than DAT_ANNUL. This will ensure that the file containing the reference is properly shut down.
One important point to note is that AGI does not check if the data being referenced is valid or not.
The default coordinate system used by AGI is an orthogonal linear system of world coordinates that increase from left to right and bottom to top. If the data coordinate system used by an application complies with these rules then a basic picture saving operation will store sufficient information to recreate these coordinates at a later stage.
If the transformation between data coordinates and the world coordinates of a rectangular piece of the display screen is more complicated than this simple system then a separate transformation has to be stored in the database to define the relationships. AGI uses the TRANSFORM facility described in SUN/61 to define the transformations. AGI does not offer the full flexibility of the TRANSFORM package as it is only interested in the limited case of transforming from the data coordinates into the flat, world coordinates of the display device.
There are two types of transformation to be defined, the first is the transformation from data to world coordinates, and the second is the transformation from world to data coordinates. Usually both will be defined, although this is not a necessity. The present implementation only allows for 2-dimensional data coordinates, and an error will be returned if the number of data variables differs from this.
The transformations are defined as character strings which describe the mathematical formulas as if they appeared in a piece of FORTRAN code. Therefore the description of the formulas should follow all the FORTRAN rules for operators and functions. As an example the case of data coordinates in polar coordinates will be used. The transformation from polar coordinates (r,θ) to Cartesian world coordinates (x,y) is defined by the equations x=rcos and . The inverse transformation is defined by the equations and . These are formulated in a program in the following way.
The transformation is then stored in the database using the routine AGI_TNEW.
If a transformation already exists in an HDS structure which converts the data coordinates into the two dimensional world coordinates of the display screen then the transformation can be copied into the database using the routine AGI_TCOPY.
The AGI interface has four routines which will perform transformations that have been stored in the database. The routine AGI_TDTOW will transform data coordinates into world coordinates, and the routine AGI_TWTOD will perform the inverse. The argument list for these routines includes a picture identifier which indicates the picture containing the transformation. If the identifier is negative then the current picture is searched. The routines take two arrays containing the x and y coordinates of the points to be transformed and returns two arrays containing the new x and y coordinates. In this context x and y need not mean a Cartesian system when used for the data coordinates, they are simply names for the first and second coordinate of the data system. In the above example r and correspond to the x and y coordinates of the data. If no transformation is found in the indicated picture then the identity transformation (output = input) is used. The transformations can be executed with double precision by calling the equivalent routines AGI_TDDTW and AGI_TWTDD.
There are a number of inquiry routines available to investigate the properties of the current picture. AGI_INAME and AGI_ICOM inquire the name and description of the current picture. AGI_ISAMD inquires if the given picture is on the same physical device as the current picture. AGI_ISAMP inquires if the given picture identifier points to the same picture in the database as the current picture identifier. AGI_IPOBS tests if the current picture is obscured either partially or totally by a specified picture in the database. Obscuration means here that the given picture intersects the current picture and that it overlays the current picture (was created more recently). The obscuration of the current picture can be tested against all subsequent pictures in the database by specifying a negative number in place of the picture identifier in the argument list. AGI_ITOBS tests the obscuration of a number of test points. The test points are specified in the coordinate system of the current picture, and each point is tested in turn for obscuration by any picture overlying the current one.
It may be desirable for an application to store information in the database that is outside the scope of the routines provided. For this reason an application can access a MORE structure using the routine AGI_MORE and save arbitrary HDS objects within it. A MORE structure can be created for each of the pictures in the database. It must be stressed that if an application uses this facility then it is responsible for the contents and whatever any subsequent application may make of them. Also an application may need to cope with the situation of a corrupted structure.
The MORE structure is accessed for reading and writing using the routine AGI_MORE
The access mode (ACMODE) controls the action of this routine. If the mode is ’WRITE’ then an HDS locator to an empty MORE structure is returned. If there was no previous MORE structure then one is created, and if there was a structure present then the previous contents are erased. At present there is no lock to prevent one application erasing a MORE structure being accessed by another. If the access mode is ’READ’ or ’UPDATE’ then the routine returns a locator to the top of the MORE structure, unless there was no structure present in which case an error is returned. The HDS locator returned by this routine has to be annulled by the calling application.
The presence of a MORE structure can be tested using the routine AGI_IMORE. The return argument is true if a MORE structure exists for the given picture, otherwise the argument is false.