NCL Website header
NCL Home > Documentation > HLUs > API

NhlNDCToData

The Fortran name of this function is NhlFNDCToData.

Given arrays containing the X and Y coordinates of points in NDC space, this function returns arrays containing the X and Y coordinates of the same points in data coordinate space.


C Synopsis

#include <ncarg/hlu/hlu.h>
#include <hfile for Transform class object>

NhlErrorTypes NhlNDCToData(
		int	pid,
		float 	*x,
		float	*y,
		int	n,
		float	*xout,
		float	*yout,
		float	*xmissing,
		float	*ymissing,
		int	*status,
		float	*out_of_range 
		)

Fortran Synopsis

      subroutine NhlFNDCToData(pid, x, y, n, xout, yout, xmissing, 
     +                         ymissing, ixmissing, iymissing, status,
     +                         out_of_range, ierr)
	  integer pid, n, ixmissing, iymissing, status, ierr
	  real x(n), y(n), xout(n), yout(n), xmissing, ymissing, out_of_range

Arguments

pid (input)
Id of a Transform class plot object with an established data transformation.
x (input)
Array of X-Axis coordinates values in NDC space.
y (input)
Array of Y-Axis coordinates values in NDC space.
n (input)
Number of elements in each of the arrays x, y, xout and yout.
xout (output)
Array for X-Axis output values in data coordinate space. The user is responsible for providing the appropriate amount of storage.
yout (output)
Array for Y-Axis output values in data coordinate space. The user is responsible for providing the appropriate amount of storage.
xmissing (input)
Missing value for the X-Axis input array. In C, it should be a pointer to this value, and if it is NULL then no missing values exist in input data.
ymissing (input)
Missing value for the Y-Axis input array. In C, it should be a pointer to this value, and if it is NULL then no missing values exist in input data.
ixmissing (input, Fortran only)
Flag for whether or not any missing values exist for the X-Axis input array; if 1, then missing values exists.
iymissing (input, Fortran only)
Flag for whether or not any missing values exist for the Y-Axis input array; if 1, then missing value exists..
status (output)
Result code of the transformation: 1 if any input array value maps to an out-of-range value; 0 otherwise (in C, it should be a pointer to this value).
out_of_range (output)
Value used in the output array for any input coordinate values that map to an out-of-range value (in C, it should be a pointer to this value).
ierr (output, Fortran only)
Error code.

Types

Type name:		NhlTErrorTypes
Definition:
typedef enum _NhlErrType{
	NhlFATAL	= -4,	/* "FATAL"	*/
	NhlWARNING	= -3,	/* "WARNING"	*/
	NhlINFO		= -2,	/* "INFO"	*/
	NhlNOERROR	= -1	/* "NOERROR"	*/
} NhlErrorTypes;

Description

This function accepts one or more coordinates in NDC space and maps the coordinates into their respective data coordinate values.

All objects that manage a data transformation have the ability to map points in NDC space to data coordinate points. You can use NhlNDCToData function to perform this operation. It accepts one or more coordinate pairs and converts them. You may specify separate separate missing values for each axis. When NhlNDCToData encounters a missing value in the input array, it does not attempt to transform it, but places it unmodified into the output array.

You must provide storage for the parameters xout and yout. The parameter n is the number of elements in the arrays x, y, xout and yout. NhlNDCToData is implemented in such a way that you can use the same storage locations for the arrays x and xout, and for the arrays y and yout if you do not mind having the input values overwritten. If you do not want NhlNDCToData to filter the input for missing values, then you should be careful to set both xmissing and ymissing to NULL.

The output parameter status is set to the value 1 if any of the input array coordinates are out-of-range across the transformation. It is set to 0 if all points (other than missing value points) were successfully transformed. The output parameter out_of_range is set to the value placed in the output array for any point that could not be transformed.


Return Values

The NhlNDCToData C function returns a value of type NhlErrorTypes, and the NhlFNDCToData Fortran subroutine returns the error in ierr. The following table indicates what the various return Error Values mean:
Value	|			Meaning
--------+-------------------------------------------------
NOERROR	|	function successful
--------+-------------------------------------------------
INFO	|	minor recoverable error
--------+-------------------------------------------------
WARNING	|	recoverable error
--------+-------------------------------------------------
FATAL	|	function failed; continuing the program
	|       may result in core dump


See Also