matrix.xl (Matrix Type Image Format Processing)

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

PROTOTYPE

xl matrix.xl / mtx-status [mtx-filename]

xl matrix.xl - - / pnm-status [pnm-filename]

xl matrix.xl / create-mtx [mtx-filename] [width] [height]

xl matrix.xl / import-pnm [pnm-filename] [mtx-filename]

xl matrix.xl / export-pnm [mtx-filename] [pnm-filename] splitmode=all

xl matrix.xl / export-pnm [mtx-filename] [pnm-filename] [x-offset] [y-offset] [width] [height] splitmode=part

xl matrix.xl / export-pnm [mtx-filename] [pnm-filename] [x-divide-nos] [y-divide-nos] splitmode=split

xl matrix.xl / import-pnm-over [pnm-filename] [mtx-filename] [x-offset] [y-offset]

xl matrix.xl / import-dted1 [target-dir] [dted1-filepath] [bib]

xl matrix.xl / block [mtx-filename] [jpg-filename] [level] [x] [y]

xl matrix.xl / copy-mtx [mtx-src-filename] [mtx-dest-filename] [channelNo.] ....

xl matrix.xl / scan-network [mtx-filename] standard [start-warp-point-file] [end-point-x] [end-point-y]

xl matrix.xl / scan-network-offset [mtx-filename] standard [start-warp-point-file] [end-point-x] [end-point-y] [dim-code-level] [dim-code-x] [dim-code-y]

xl matrix.xl - - / leveling-mtx [mtx-filaname]

ARGUMENTS

[mtx-filename] Matrix file name

[pnm-filename] PNM file name

[jpg-filename] JPEG file name

[dted1-filepath] File path of a DTED1 type file

[bib] A bib file with bib elements extracted from a crd file

[width] Image width, number of pixels

[height] Image height, number of pixels

[x-offset] Image saving start position. Number of pixels offset in the x direction of a matrix file

[y-offset] Image saving start position. Number of pixels offset in the y direction of a matrix file

[x-divide-nos] Number of image divisions in the x direction, for export-pnm

[y-divide-nos] Number of image divisions in the y direction, for export-pnm

[level] Hierarchy level of an image

[x] Coordinate position of an image, x coordinate of the matrix file

[y] Coordinate position of an image, y coordinate of the matrix file

[mtx-src-filename] Copy source matrix file name

[mtx-dest-filename] Copy destination matrix file name

[channelNo.] Channel number or channel flag

[start-warp-point-file] File in which warp point data is saved. Warp point data refers to text data obtained by clicking "Edit" and then "Copy Place Info." Menu (Edit Menu)

[end-point-x] X-coordinate of the end of scan data. Base coordinate values of warp point data specified by [start-warp-point-file].

[end-point-y] Y-coordinate of the end of scan data. Base coordinate values of warp point data specified by [start-warp-point-file].

Option

Options in create-mtx
default_color= [default_color] The default is -1.
Options in import-pnm-over
transparent= [transparent_color] The default is 16777215.
leveling= on/off The default is on.
Options in scan-network
meta= [bib file name]
leveling= [on/off] The default is off.
Options in export-pnm
splitmode= [all/part/split] The default is all.
level= integer The default is

ENVIRONMENT

Agent xl [UNDEF REF (xl)], gbmx gbview

EXPLANATION

This script is used to perform operations related to matrix data. The script can currently only be applied to 8 bit RGB type images. The first argument indicates the operation, which is defined as follows.

mtx-status
This option returns the status information of a given matrix file. Please refer to the Matrix Format Specification for the detailed explanation. Since the status is the return value of the XLscript, it is necessary to enable the standard output.
% xl matrix.xl - - / mtx-status
This is why "- -" is inserted.
pnm-status
This option returns the status information of a given PNM file. Please refer to the netpbm Manual for the detailed explanation.
create-mtx
This option generates an empty matrix file of a given size ( pixel size). It is equivalent to a totally transparent image when referenced.
Specify a color conceptually assumed to be set before writing for the default_color option. This must be a RGBA 32-bitvalue. A=00 is completely opaque and A=FF is completely transparent.
import-pnm
This option converts a given PNM file into a matrix file with a given name. The image will have the same size in number of pixels.
export-pnm
In version ver.B.b17.01 or earlier, this argument converts a given matrix file to a PPM file with a given name. The image will have the same size in number of pixels. In version ver.B.b17.02 or later, a function for outputting images of various sizes has been added, which is explained below.
From ver.B.b16.14, it is possible to specify the level option and convert data in each hierarchy in a matrix. The default is level=0. The number of pixels of each layer of the matrix varies depending on the settings of the matrix.
This option converts a given matrix file to a PPM file with a given name. There are three formats. If only input file and output file names are specified, an image with the same number of pixels as the input matrix file is output to the output file. You can also specify the option splitmode=all as well. If you specify the level option, you can output images at any level.
If you specify four values for [x-offset], [y-offset], [width], and [height] in addition to the input file and output file and specify splitmode=part , an image of size [width] times [height] is cut out starting at the given offset. The level option can be used. Moreover, the splitmode option can be omitted.
If you specify [x-divide-nos], [y-divide-nos], and splitmode=split in addition to the input file and output file names, the image is divided into [x-divide-nos] parts in the x direction and [y-divide-nos] parts in the y direction and output into several PPM files. Since the image file is automatically assigned the name [pnm-filename]-[index number in the x direction]-[index number in the y direction].ppm, no extension should be specified for [pnm-filename]. The split-mode=on option cannot be omitted.
import-pnm-over
This option embeds a given PNM file ( [pnm-filename]) into an existing matrix file ( [mtx-filename]). The embedding position is given by [x-offset],[y-offset].
Specify colors to be eliminated for the transparent option as 24-bitRGB values. In other words, all parts of the image with the color specified by the transparent option will be assigned the originally written color. If this option is not specified, all colors are overwritten.
The leveling=off option is valid in ver.B.b16.14. If this option is specified, leveling is not performed. It is a convenient option when importing files in a batch and determining their layers at the end.
import-dted1
This option reads a DTED1-type file and generates a matrix file, which is a 2-dimensionalarray of 16-bitsigned ( complement of integers, along with object files such as .crd that reference it. For example, execute the following command.
```
xl matrix.xl - - / import-dted1 test 'area01/dted/*/*.dt1' bib.xl
 
```
[dted1-filepath] shall be specified as a file path to a directory where a series of DTED1-type files are saved and a file path down to file name. Specifically, in case of the DTED1 format, the file name and the directory name including the file express the latitude and longitude directly and this information is thus essential; an error occurs if a file path is not specified. Note also that multiple files are specified in the example above by using wild cards for the parts corresponding to latitude and longitudae.
bib.xl corresponding to [bib] is a bibliographic information file with the same format as worldfile-mtx.xl etc. This file contains bibliographic information of data to be disclosed, for example using the following format.
```
<?xl version="0.1" encoding="EUC-JP"?>
<bib xmlns:gb="xlp://isjhp1.nichibun.ac.jp:8080/gb_metadata">
   <gb:title type="text" data="Japan Ortho"/>
   <gb:creator type="text" data="Osaka City University"/>
   <gb:content.period type="W3C-DTF" data="2003-01-01 / 2003-01-01"/>
   <gb:issue.period type="W3C-DTF" data="2006-06-01"/>
   <gb:property type="gb-prop" data="photo"/>
   <gb:homepage type="URL" data="http://www.osaka-cu.ac.jp/"/>
</bib> 
```
block
This option extracts a JPEG image at a given coordinate position ( [level] [x] [y]) from a matrix file [mtx-filename]. The extracted image is saved in the file specified by [jpg-filename].
copy-mtx
This option generates a matrix file named [mtx-dest-filename] that contains the same header information as the matrix file specified by [mtx-src-filename] and copies only the channels given by [channelNo.] for all nodes within [mtx-src-filename]. It is possible to specify multiple channels for [channelNo.].
If you want to generate a matrix file including only transmission data from a generated matrix file, you can issue the following command.
```
% xl matrix.xl - - / copy-mtx srcfile.mtx destfile.mtx MF_SEND MF_SEND_VISU MF_SEND_FILE
 
```
Note that the following channels are currently defined in matrix_RGB8.xl.
- 8Transmission blocks ( compressed jpeg)
- 9Non-compressed RGB images
scan-network
This function scans maps on the network and creates a single matrix image file with the name specified by [mtx-filename].
The scanning is started from warp point data saved in the file specified by [start-warp-point-file]. Warp point data is stored using the following format and can be obtained by selecting "Edit" and then "Copy Location Info" in COSMOS Menu (Edit Menu). In order to obtain the warp point data required, use COSMOS' browse function to display the image you want to scan, zoom to the desired location to start scanning at the desired scanning resolution, select the menu item and save the image to a new file.
```
<warp-point>
	<tracking-time>197748854sec</tracking-time>
	<title>China</title>
	<type>2</type>
	<query><OR>
		<query qtype="URL" title="test-C118" id="0" active="off">
			<URL>xlp://gbs2.itakura.toyo.ac.jp:8080/wakashima/C118/C118.crd</URL>
		</query>
		<query qtype="property" id="0" active="off">
			<qualifier cond="part">xlp://isjhp1.nichibun.ac.jp:8080/gb_metadata 0 property () plot</qualifier>
		</query> 
		<query qtype="property" title="Archiology" id="0" active="off">
			<AND>
				<qualifier cond="part">xlp://isjhp1.nichibun.ac.jp:8080/gb_metadata 0 property () base</qualifier> 
				<qualifier cond="boundary">xlp://isjhp1.nichibun.ac.jp:8080/gb_metadata 0 content.period W3C-DTF ^"100-*-*.*.*:*:* / 300-*-*.*.*:*:*"</qualifier>
			</AND>
		</query> 
		.......
		</OR>
	</query> 
	<resolution>2.500000 </resolution> 
	<rotate>0.000000 </rotate> 
	<center>130.000000  0.000000 </center> 
	<base>xlp://localhost:8080/test/China.crd</base> 
	<layers>
		<entry>xlp://localhost:8080/test/China.crd 256</entry>
	</layers>
</warp-point>
 
```
The matrix.xl script reads warp point data and sets the base coordinate system to the coordinate system specified by the base element. In this coordinate system, scanning is started from the coordinates specified by the center element of warp point data at the resolution given by the resolution element, and stopped at the coordinates specified by [end-point-x],[end-point-y]. [end-point-x],[end-point-y] must be larger than the coordinate values of the center element. Moreover, rotation is ignored; scanning is performed in parallel with the x or y axis.
The query element specifies search criteria for the coordinate systems. All coordinates matching the criteria are overlapped. In other words, it is useful when scanning a large coordinate system containing data represented in multiple sub-coordinate systems.
A matrix file specified by [mtx-filename] is saved as matrix data, with the scanning start position at the position of (0,0) and scanning end position at the position of the maximum X and Y pixel values.
Note that if no option is specified, the matrix will be saved without layers. It is possible to convert data of a connected image into a pnm file via export-pnm at this point. This also means that it is possible to save time for leveling and create a connected image.
In order to set layers in a matrix, you can specify leveling=on as an option first or execute the command without any options and then use the leveling-mtx function of matrix.xl to set the layers. By setting layers, you can create matrix data that can be published on the network.
If you specify meta=[meta data file name], crd, map and lst files can be created. By executing the makefile.xl script after operation, all information that can be published is generated. If you specify the meta option, the leveling option is automatically set to on. An example of a meta data file ( bib file) is shown below.
```
<?xl version="0.1" encoding="EUC-JP"?>
<bib xmlns:gb="xlp://isjhp1.nichibun.ac.jp:8080/gb_metadata">
   <gb:title type="text" data="Japan Ortho"/>
   <gb:creator type="text" data="Osaka City University"/>
   <gb:content.period type="W3C-DTF" data="2003-01-01 / 2003-01-01"/>
   <gb:issue.period type="W3C-DTF" data="2006-06-01"/>
   <gb:property type="gb-prop" data="photo"/>
   <gb:homepage type="URL" data="http://www.osaka-cu.ac.jp/"/>
</bib> 
```
scan-network-offset
This function scans maps on the network and creates a single matrix image with the name specified by [mtx-filename]. This function is different from scan-network in that the scanned data is saved from the position of dimension code specified at the end of the argument.
leveling-mtx
This function is supported from ver.B.b16.14. It sets the layer in a given matrix [mtx-filename]. For example, it can be used when a matrix is composed by import-pnm without layers, in order to set the layer to the results in a batch at a later stage.

The matrix-type format supports long filenames. However, in order to use the long filenames, it must be permitted in your OS and file system as well.

In the future, layer support will be built into the raster format r64/cr and the vector format pdbp, which were employed during the early development of GLOBALBASE, and these formats will gradually be integrated into the matrix-type format.

[UP] Go To Page Top

RETURN VALUE

ERRORS

REFERENCE

BUGS

[UP] Go To Page Top