gmxPgPlotField

Author: Hiroshisa Mori / joshua@globalbase.org + [Transrate]Reiko Inoue Bendtsen c/o Suzaku Translations / (http://www.suzaku-translations.com/) +

PROTOTYPE

(1) <gmxPgPlotField/>

(2) <gmxPgPlotField> field-opt-list ... </gmxPgPlotField>

ARGUMENTS

field-opt-list [1] XLT_PTR [UNDEF REF (XLT_PTR)]: Pointer to the work area of matrix field data

... A data group determined by the [1+] merge-type attribute

ATTRIBUTES

id (1)(2) [mandatory] Integer: Matrix identifier

csv (1) [not required] (2) [arbitrary] Character string: A,B,C,.... Row in a CSVfile

label (1) [not required] (2) [arbitrary] Number: Matrix attribute number

dim (1) [不要] (2) [arbitrary] Number: Matrix dimension number

merge-type (1) [not required] (2) [mandatory] Character string: Attribute detailed type

EVALUATION TYPE

applicative

AGENT(S) BELONGS

gbmx

ENVIRONMENT BELONGS

Env0

EXPLANATION

This function match rows in a CSV file to a matrix's plot data attribute numbers or dimensions. The correspondence table is stored at an address given by field-opt-list . The prototype (1) generates a work area for the matrix field data and returns a pointer to it. The progotype (2) specifies the pointer to the work area field-opt-list and creates a correspondence table there.

The prototype (1) requires only the matrix identifier id as an attribute value. The prototype (2) requires the following combinations of attribute values. Attribute values indicated as "mandatory" are required, while attribute values indicated as "x" are not required.

Table Necessity of attribute values

	id	csv	label	dim	merge-type
[1] (1)	mandatory	x	x	x	x
[2] (2) Correspond to dimension numbers	Mandatory	Mandatory	x	Mandatory	Mandatory
[3] (2) To attribute numbersattribute, constant value	Mandatory	x	Mandatory	x	Mandatory
[4] (2) To attribute numbers, CSV	Mandatory	Mandatory	Mandatory	x	Mandatory

Some usage examples are shown below.


[2]
<gmxPgPlotField id="^mtx" csv="A" merge-type="^mxPgTYPE_INT" dim="0">
  ^Fields ^mxPgFDIT_DD ^reso (* 180 reso) 0</gmxPgPlotField>


[4]
<gmxPgPlotField id="^mtx" csv="C" merge-type="^mxPgTYPE_STRING" label="5">
  ^Fields utf-8 ([quote type="direct"] '([field name="LABEL"] ($ ___convert)))</gmxPgPlotField>
[3]
<gmxPgPlotField id="^mtx" merge-type="^mxPgTYPE_RGBA" label="0">
  ^Fields 0 0xff000000</gmxPgPlotField>
[4]
<gmxPgPlotField id="^mtx" csv="D" merge-type="^mxPgTYPE_STRING" label="1">
  ^Fields utf-8 () test-http </gmxPgPlotField>

As already explained, the instruction [1] generates a work area. The method [2] acquires coordinate values from a CSV file. The method [3] sets a constant value for all the plots. The function [4] processes CSV values and assigns them to attribute numbers of plots.

id
Specify a matrix ID
csv
Specify numbers of rows A, B, C... corresponding to attributes of csv. This XML attribute can be omitted.
label
This XML attribute is used in patterns [3] and [4]; it specifies a matrix's attribute number. Rows in the csv XML attribute are matched with the plot attribute numbers specified by the label XML attribute. If the csv XML attribute is omitted, data value given by the element data of gmxPgPlotField is saved commonly in labelattribute numbers of all plots.
Although the label XML attribute can be omitted, either the label XML or dim XML attribute must exist.
dim
This XML attribute is used in pattern [2] and specifies a matrix's coordinate axis number. As an original function of a matrix, values up to the number of dimensions of a matrix minus 1can be specified; however, as plot-csv.xl supports only two-dimensional matrices, only 0or 1can be specified. 0refers to the x axis while 1refers to the y axis.
Although the dim XML attribute can be omitted, either the label XML or dim XML attribute must exist.
merge-type This attribute specifies a matrix's detailed attribute type.

Lastly, the element data of gmxPgPlotField is given differently depending on the data type given by the merge-type XML attribute.

mxPgNONE
None
mxPgSTRING
[Pointer to work area] [saved character code name] [conversion formula] [initialization character string: arbitrary]
If [conversion formula] is () , no special processing is performed on the CSV data, which is set as attribute values. If [conversion formula] is specified as a conversion formula given as an XL formula, CSV values converted by the formula is set as attribute values. The example [4] corresponds to this case. The CSV values are stored in the area of ___convert. The actual conversion is executed when a CSV table is created for the first time; a $ symbol cannot be interpreted at this point and it is thus necessary to use direct quotes.
If the csv attribute is not specified, [initialization character string: arbitrary] becomes necessary. This character string is passed to [conversion formula] and set as the attribute of all plots as a constant value.
mxPgINT_ADD mxPgINT_MAX mxPgINT_MIN
[Pointer to work area] [data type in CSV] [conversion resolution] [conversion offset] [count] [initialization character string: arbitrary]
Data in a CSV file is first interpreted as the data type indicated by [data type in CSV] , which is read as double-precision floating point. The detailed explanation on [data type in CSV] will be given later. The data read is converted by the formula ( [read data]x[conversion resolution]+[conversion offset]). Any fractions after the conversion are omitted, so that the converted output is an integer, and the result is set as the attribute data or coodinate value of the matrix. [Conversion resolution] and [conversion offset] must be given as double-precision floating point values.
[count] is ignored in these three data types; it is sufficient to specify 0for the attribuite.
If no csv attributes are specified, [initialization character string: arbitrary] becomes necessary; this character string is given to [conversion formula] and set for all plot attributes as a constant value.
mxPgINT_AVG
[Pointer to work area] [data type in CSV] [conversion resolution] [conversion offset] [count] [initialization character string: arbitrary]
The method of calculating the attribute data is the same as above. mxPgINT_ADD mxPgINT_MAX mxPgINT_MIN This data and [count] are saved as attribute data, as a pair of integer values. In case of this type, in order to merge plots with higher layers of a matrix , the average of each plot is taken and set as a new plot attribute value. This average is cultulated weighted by [count] and the [count] in the higher layers becomes the total value of [count] of lower layers.
If no csv attributes are specified, [initialization character string: arbitrary] becomes necessary. This value is passed to the conversion formula above and set as the attribute of all plots as a constant value.
mxPgRGBA
[Pointer to work area] [count] [initialization RGBA: arbitrary]
This function acquires RGBA data from a CSV file and assigns it to plot attributes. If it is given as hexadecimal, the format used in the C language to specify pixel values, for example -16777216,must be used. [count] works in the same way as integer type [count] and used for weighting when calculating colors of higher layers. No weighting is performed if 0is specified.

If no csv attributes are specified, [initialization RGBA: arbitrary] is required. This value is passed to the conversion formula above and set for all plot attributes as a constant value.

Integer type [data type in CSV] The following values can be specified for this type.

mxPgFDIT_INT
The CSV data type is integer ( 64-bitinteger).
mxPgFDIT_FLOAT
The CSV data type is double-precision floating point.
mxPgFDIT_DD
The CSV data type is decimal point expression of latitude and logitude, for example means 135degrees 30minutes.
mxPgFDIT_DDMMSS
The CSV data type is sexagesimal expression of latitude and logitude, for example means 135degrees 50minutes 12seconds.

[UP] Go To Page Top

RETURN VALUE

If mode ="meta," a gmxStatus list is returned.

If mode is omitted, XLT_RAW [UNDEF REF (XLT_RAW)]-type node information is returned. The XLT_RAW information includes the followings.

nlist_type 1byte
Format type of child node list
- 0:Bit field type
- 1:dim_code enumeration type
Child node list: In case of bit field type
1. nlist_dim_bit_field_len
  Bit field length: compressed_code 64format integer
2. nlist_dim_bit_field
  Bit field with a length of nlist_dim_bit_field_len
Child node list: In case of dim_code enumeration type
1. nlist_dim_addr_len
  Number of dim_codes counted: compressed_code64 format integer
2. dim_codes
  dim_code for the number of nlist_dim_addr_len. Each dim_code is a row of compressed_code64 format integers
channel_data
Channel data Each channel data is formatted in the following order, repeated for the number of required channels.
1. id
  Channel ID: compressed_code 64format
2. len
  The length of the channel data itself, compressed code 64format
3. data
  The data itself. The format conform to the format of each data type.

ERRORS

XLE_SEMANTICS_TYPE_MISSMATCH [UNDEF REF (XLE_SEMANTICS_TYPE_MISSMATCH)]
The types of filename or point-data do not match.
XLE_PROTO_INV_PARAM [UNDEF REF (XLE_PROTO_INV_PARAM)]

REFERENCE

BUGS

[UP] Go To Page Top