PCIADD2

Description

Adds one new image channel to a TILED, BAND or FILE interleaved PCIDSK image file, with the input channel stored in an external file. An image channel can be added to an existing image file, or to a new, empty image file to hold the output.

Parameters

pciadd2(file, datatype, addmode, ifile, chaninfo)

Name	Type	Caption	Length	Value range
FILE *	str	Input file name	1 -
DATATYPE	str	Output raster data type	0 - 4	8U \| 16S \| 16U \| 32R \| C16S \| C32R Default: 8U
ADDMODE *	str	Add File Mode: CREATE/EXIST	5 - 6	CREATE \| EXIST
IFILE	str	New image file name	0 -
CHANINFO	List[int]	Channel layout information	0 - 4

* Required parameter

Parameter descriptions

FILE

Specifies the name of the PCIDSK database file to receive the new image channel.

DATATYPE

Specifies the data type for the output image channel.

Valid data types are:

8U: pixels are stored as 8-bit unsigned integer integer values; this is the default value
16S: pixels are stored as 16-bit signed integer values
16U: pixels are stored as 16-bit unsigned integer values
32R: pixels are stored as 32-bit real values
C16S: pixels are stored as 16-bit signed integer complex values
C32R: pixels are stored as 32-bit real complex values

ADDMODE

Specifies the mode for adding a new image channel.

Supported options are:

CREATE: creates a new, empty image file to hold the new channel
EXIST: adds the new channel to an existing image file

IFILE

Specifies the name of the new image file to add to the PCIDSK header file.

If ADDMODE="CREATE" and IFILE is not specified, the new image file will have the same file name as the input image file, and will use the three-digit channel number (with leading zeroes) as the file extension (.nnn).

If ADDMODE="EXIST", IFILE must be specified.

CHANINFO

Optionally specifies information about the layout of the image data channel within the file specified by IFILE.

For 'raw' files (that is, those that have no header information and only a single packed channel), this parameter should be defaulted. CHANINFO is used only if ADDMODE="EXIST".

Specify this parameter as follows:

RAW files:	(nothing)
Other files:	header, pixelgroup, linelength, swap

where:

header: number of bytes before the first byte of channel data

Default: 0 bytes
pixelgroup: number of bytes in each group of pixels

Default: from DATATYPE (8U=1, 16S=2, 16U=2, 32R=4, C16S=4, C32R=8)
linelength: number of bytes in one line of image data

Default: pixelgroup * database size in X (pixels)
swap: 16-bit or 32-bit real data swap flag

If swap=1, data is byte-swapped (that is, low order byte first). Byte-swapped data is common on PCs and DEC machines.

Default: native byte order for this system

Details

PCIADD2 adds one image channel to a PCIDSK image file (FILE). The specified file must be either BAND- or FILE-interleaved. PIXEL-interleaved files cannot have external image channels added. The image data type (DATATYPE) can be 8-bit unsigned (8U), 16-bit signed (16S), 16-bit unsigned (16U), 32-bit real (32R), 16-bit signed complex (C16S), or 32-bit real complex (C32R). The file (IFILE) that receive the new image data is either created (ADDMODE="CREATE") or already exists (ADDMODE="EXIST").

The channel number for the new image is the first available channel in the image file, and can either be a channel previously deleted by PCIDEL2, or the next sequential channel after the last channel in the file.

If ADDMODE="CREATE", a new image file of the appropriate size is created, and initially contains zeros (no useful data). If IFILE is not specified, the image file is created, using the same name as the database file and the three-digit channel number (with leading zeroes) as the file extension (.nnn). If the image file already exists, the new channel is not created.

If ADDMODE="EXIST", an image file of appropriate size and type must already exist, and must contain valid image data. IFILE must be specified; there is no default file name. The image file is assumed to have the same number of pixels and lines as all other image channels on the database.

The CHANINFO parameter can be used to specify how the channel of information in an existing file (when ADDMODE="EXIST") is organized. If the data is in 'raw' format (no header information, single packed channel of data), this parameter may be defaulted. If the file is not in 'raw' format, careful use of the CHANINFO parameter can allow access to the channel of data.

Warning: Ensure that the size and data type for existing image files are correct for the specified database file; otherwise, programs that access data on the image channel may not perform as expected.

Unlike pixel-interleaved PCIDSK files created by CIM, the data type for image channels on band- or file-interleaved PCIDSK files do not need to follow a particular order. The data type (DATATYPE) for additional image channels may be anything, and does not depend on the data types of existing channels on the database.

Example

Add a new 16-bit signed image channel to a 512x512 PCIDSK file created by CIM, which already contains six image channels.

from pci.pciadd2 import pciadd2

file	=	"image.pix"
datatype	=	"16S"
addmode	=	"create"
ifile	=	""
chaninfo	=	[]

pciadd2( file, datatype, addmode, ifile, chaninfo )

Environments	PYTHON :: EASI
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Example :: Related