1STUIXY(3NCARG)                   NCAR GRAPHICS                  STUIXY(3NCARG)
2
3
4

NAME

6       STUIXY - Inversely maps a single point on the streamline from user to
7       data coordinate space.
8

SYNOPSIS

10       CALL STUIXY (XUS,YUS,XDA,YDA,IST)
11

DESCRIPTION

13       XUS         (REAL, input): The X coordinate of a point in the user
14                   coordinate system.
15
16       YUS         (REAL, input): The Y coordinate of a point in the user
17                   coordinate system.
18
19       XDA         (REAL, output): The X coordinate of the point in the data
20                   coordinate system.
21
22       YDA         (REAL, output): The Y coordinate of the point in the data
23                   coordinate system.
24
25       IST         (REAL, output): Status of the mapping operation: 0
26                   indicates success, negative values indicate that the
27                   mapping failed; positive values are reserved and should not
28                   be used by the implementor of a mapping routine.
29

USAGE

31       STUIXY is a user-modifiable routine provided to support custom mappings
32       of the data coordinate space. The user does not invoke it directly.
33       Instead, whenever the parameter MAP specifies a mapping not handled by
34       Streamlines internally (i.e., when MAP is set to a value other than 0,
35       1, or 2), Streamlines calls STUIXY once for each incremental step in
36       the creation of a streamline. The default version of STUIXY simply
37       performs an identity mapping. In order to implement a custom mapping,
38       you must pick a unique mapping code (a positive integer greater than
39       2), and then modify each of the three routines, STUMXY, STUIXY, and
40       STUMTA to recognize and respond consistently to the chosen code. In the
41       standard distribution of NCAR Graphics, these three routines reside in
42       a single file, ´stumxy.f´.  STUMXY maps a point from data to user
43       coordinate space, STUIXY inversely maps a point from user to data
44       coordinate space, and STUMTA, which is likely to be the most difficult
45       to implement, finds the tangent angle of the streamline at a point in
46       NDC space.
47
48       STUIXY has access to a common block called STMAP that contains a number
49       of variables used to record the current transformation state. In order
50       to accommodate a variety of mapping implementations, STMAP provides
51       more information than normally required. Consider the values stored in
52       STMAP as strictly read-only. One essential member of this common block
53       is IMAP, which contains the value currently assigned to the MAP
54       parameter.
55
56       In STUIXY, the implementor of a custom mapping needs to add code of the
57       form:
58
59            IF (IMAP .EQ. <chosen_map_code>) THEN
60
61                ...map XUS to XDA
62
63                ...map YUS to YDA
64
65                ...if error, set IST to a negative value
66
67                RETURN
68
69            ENDIF
70
71       Note that after the return from STUIXY, Streamlines checks to ensure
72       that XDA and YDA are within the current boundaries of the data
73       coordinate system.
74
75       When implementing a custom mapping, you may wish to look at the coding
76       of the pre-defined mappings (0, identity mapping; 1, Ezmap projections;
77       and 2, polar coordinate mapping) in the file ´stmpxy.f´. For these
78       mappings, the subroutine STIMXY is the equivalent of STUIXY; it has an
79       identical interface and may serve as a model for your implementation.
80

ACCESS

82       To use STUIXY, load the NCAR Graphics libraries ncarg, ncarg_gks, and
83       ncarg_c, preferably in that order.
84

SEE ALSO

86       Online: stgetc, stgeti, stgetr, stinit, stream, streamlines,
87       streamlines_params, strset, stsetc, stseti, stsetr, stumsl, stumta,
88       stumxy, ncarg_cbind.
89
90       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
91

93       Copyright (C) 1987-2007
94       University Corporation for Atmospheric Research
95
96       This documentation is free software; you can redistribute it and/or
97       modify it under the terms of the GNU General Public License as
98       published by the Free Software Foundation; either version 2 of the
99       License, or (at your option) any later version.
100
101       This software is distributed in the hope that it will be useful, but
102       WITHOUT ANY WARRANTY; without even the implied warranty of
103       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
104       General Public License for more details.
105
106       You should have received a copy of the GNU General Public License along
107       with this software; if not, write to the Free Software Foundation,
108       Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
109
110
111
112UNIX                              April 1993                    STUIXY(3NCARG)
Impressum