PSGIMAG

Description

Generates a three-dimensional perspective rendering, using input imagery and elevation data.

Note: This program uses a large amount of RAM memory; see the Memory Usage section for more information.

Parameters

psgimag(fili, dbic, dbec, escale, filo, dboc, backcol, edgecol, dbow, vpoint, vfield, vangle, frontpix, dbvs, backelev)

Name	Type	Caption	Length	Value range
FILI*	str	Input file name	1 -
DBIC*	List[int]	Database input channel list	1 - 3
DBEC*	List[int]	Specified the channel that contains the elevation data.	1 - 1
ESCALE	List[float]	Elevation Scale and Offset (m)	0 - 2	scale, offset Default: 1,0
FILO*	str	Output file name	1 -
DBOC*	List[int]	Database output channel list	1 - 3
BACKCOL	List[int]	Background color (RGB)	0 - 3	0,0,0 - 255,255,255 Default: 0,0,0
EDGECOL	List[int]	Edge Color (RGB)	0 - 3	0,0,0 - 255,255,255
DBOW	List[int]	Output window	0 - 4	Xoffset, Yoffset, Xsize, Ysize
VPOINT	List[float]	Viewing position (X,Y,Z)	0 - 4	Xpos, Ypos, Zpol, Zrel
VFIELD	List[float]	Field-of-view angle	0 - 1	0 - 170 Default: 0
VANGLE	List[float]	Viewing angles	0 - 2	0,0 - 360,90 Default: 180,30
FRONTPIX*	List[float]	Number of foreground pixels	1 - 1	1 -
DBVS	List[int]	Input vector segment(s)	0 - 6	0,0,0,0,0,0 -
BACKELEV	List[float]	Undefined elevation value	0 - 1

* Required parameter

Parameter descriptions

FILI

Specifies the name of the PCIDSK file from which image, elevation, and vector data is to be taken.

DBIC

Specifies 1 to 3 channels to use as input imagery.

If a single channel is specified, input is Black and White.

If three channels are specified, input is RGB (red, green, blue).

Notes:

Input imagery should be pre-enhanced and be in 8-bit channels.

DBEC

Specifies the channel containing elevation data.

ESCALE

Optionally specifies the scale and offset to apply to the elevation values in the elevation channel (DBEC) to convert values to meters.

If unspecified, scale defaults to 1, and offset defaults to 0.

scale: scale (no offset)
scale, offset: scale and offset

The equation for the conversion is:

elevation in meters = scale * (value + offset)

For example, to convert elevation values from feet to meters, where a value of 0 represents 1000 feet:

0.3048,1000        : meters = 0.3048 * (value + 1000)

Notes:

It is possible to exaggerate the effect of elevation by using a larger scale value.

It is critical that the ground size of pixels be properly set. This is done when the file is created (for example, CIM function); alternatively, it can be set directly using the APS function.

FILO

Specifies the name of PCIDSK file to which the generated perspective scene will be transferred. FILO must exist before running PSGIMAG.

FILO can be the same as FILI.

DBOC

Specifies which channels in FILO will receive the generated perspective scene.

If a single channel is specified, output is BW (black and white).

If three channels are specified, output is RGB (red, green, blue).

Notes:

The number of channels specified by DBOC and DBIC must be same.

BACKCOL

Specifies the background (sky) color for the generated perspective scene.

Each background color is in the range of 0-255.

A color can be specified for each channel in the output scene. If no colors are specified, the default is 0. If only one color is specified, that color is used for all other unspecified channels. If more colors are specified than there are channels in the output file, only as many colors as channels are used.

Background color is typically set to 0,0,0 (black), or variations of light blue (for example, 0,160,255) to simulate the sky.

EDGECOL

Optionally specifies colors for the sides of the generated perspective scene. By default, no color is applies to the scene edges.

Each background color is in the range of 0-255.

A color can be specified for each channel in the output scene. If no colors are specified, the default is 0. If only one color is specified, that color is used for all other unspecified channels. If more colors are specified than there are channels in the output file, only as many colors as channels are used.

Edge color is typically set to the same as BACKCOL (Background Color), or variations of gray (for example, 80,80,80).

DBOW

Optionally specifies a rectangular window in the output channels in which the generated perspective scene will be embedded.

By default, the perspective scene is embedded in the entire channel.

VPOINT

Specifies the viewing position of the observer.

Values include:

Xpos: X viewing direction, in pixels. Default is the middle of the input window.
Ypos: Y viewing direction, in lines. Default is the bottom of the input window.
Zpos: viewing height above sea level, in meters. Default is ground level at Xpos, Ypos elevation.
Zrel: viewing height above surface, in meters. No default value; if Zrel is specified, Zpos is ignored; otherwise, Zpos is used.

You can default Zpos and Ypos, or Zpos, Ypos, and Xpos. Or you can specify all three values. Zrel represents an alternate Z dimension; when it is specified, Zpos is ignored.

VFIELD

Specifies the angle of the field of view (viewing cone) in the scene, in degrees from 0 to 170.

The field of view is comparable to camera focal length in photogrammetry; it defines the perspective for the generated scene.

For example:

170: provides a wide-angle view
60: provides a "human eye" perspective
0: provides an isometric view with no perspective; this is the default value

VANGLE

Specifies the viewing angles in terms of direction and inclination.

If no angles are specified, the defaults are:

direction: 180 degrees
inclination: 30 degrees

The direction angle is expressed in degrees using the following convention:

Example for an MxN image:
               0               
               ^               A direction of 0 looks from
               |               the bottom of the image (line N)
               |               to the top of the image (line 1).
   270 <-------+-------> 90
               |               A direction of 270 looks from the
               |               right of the image (pixel M) to
               V               the left of the image (pixel 1).
              180

The inclination value is expressed in degrees from 0 to 90 and specifies the angle for tilting the earth. This is useful for viewing objects positioned behind others, and provides a greater feeling of depth. A value of 0 provides a profile, 90 offers a straight-down view, and 30 provides a 'human eye' view.

FRONTPIX

Specifies the number of foreground pixels that are represented across the front of the output window.

Depending on the value specified, FRONTPIX (Number of Front Pixels) magnifies or shrinks the size of the foreground pixels. The amount of magnification is calculated as DBOW(3)/FRONTPIX.

FRONTPIX must be greater than 0; a typical value is 128. If a parallel view is being generated, this parameter is often set to the same value as DBOW(3), providing no magnification.

Note: If the viewpoint of the perspective scene is high above ground level, the foreground may appear to have many more pixels than specified by this parameter, due to perspective. Using a very small or very large value may generate a poor result.

DBVS

Specifies the name of the file that contains the input vector segments to be draped on the generated perspective. The input vector segement consists of sets of vectors (type VEC:116); up to 6 sets of vectors can be connected.

Vector sets are colored: red, green, blue, yellow, black, white. In BW perspectives, all vectors are colored white (except black).

Vectors typically represent elements such as roads, rivers and streams, contours, etc.

Vectors are always drawn 1 pixel wide, regardless of the perspective or foreground zooming.

BACKELEV

Optionally specifies a value which is used as a background (undefined or unknown) elevation. If specified, pixels in the elevation channel with this value are ignored and not rendered. If defaulted, no background value is defined and all pixel are valid.

Details

PSGIMAG generates a three-dimensional perspective rendering using imagery and elevation data.

Most imagery in remote sensing applications is taken from high altitudes looking straight down. It is occasionally useful, however, to simulate the view an observer would have if he were standing on the ground looking out over the image at an oblique angle. This is generally known as "Perspective Scene Generation" and requires that elevation data be available for each pixel in the input imagery.

The parameters FILI, DBIC, and DBEC describe where the input imagery and elevation data are obtained.

The parameter ESCALE (Elevation) describes how to convert the elevation values in the input channel into meters.

The parameters FILO, DBOC, and DBOW define the output for the generated scene.

The parameters BACKCOL (Background Color) and EDGECOL (Edge Color) describe how to color the background and scene edges for best effect.

The parameters VPOINT (Viewpoint), VFIELD (Field of View), and VANGLE (Direction/Inclination) all describe the imaginary observer's viewpoint.

The parameter FRONTPIX (Front Pixels) defines the magnification level of the pixels rendered in the output window.

The parameter DBVS optionally specifies sets of vectors, held in vector segments, to drape over the rendered perspective. Vectors are drawn 1 pixel wide, regardless of distance or perspective. The first set of vectors is always drawn in red, the second in green, third in blue, fourth in yellow, fifth in black, and sixth in white. Because vector segments can be duplicated in DBVS, a specific color can be obtained by specifying a particular segment multiple times. For example, if segment 26 contains rivers and streams, these could be shown in blue by specifying segment 26, three times.

PSGIMAG will write segment 26 in red, then in green, and then in blue. Because blue was written last, only blue would be visible. Keep this overlapping feature in mind when you list these channels; the most important vector should be listed last so that it is not overlapped by other vector data.

If a single channel perspective is being generated (for example, b&w), all vectors are drawn in white except the fifth set, which is still drawn in black.

Occasionally, the elevation in some areas of the input data (DBEC) is unknown or not relevant. This elevation should be set to a specific background value. This value, passed to PSGIMAG using the BACKELEV (Background Elevation Value) parameter, specifies that pixels of that color will not be rendered. If BACKELEV is not specified, all elevation data is considered valid.

Note: BACKELEV can be useful for generating a rendering of an arbitrarily shaped region. For example, a bitmap mask of unwanted areas is generated and a background value is burned into the areas under the mask (using the MAP function, for example).

The many parameters in PSGIMAG, combined with the concepts of perspective geometry, angles and position can make PSGIMAG initially difficult to use. Sketching out the extent of the database and carefully determining the view point (VPOINT) and viewing angles (VANGLE) can make PSGIMAG much simpler to understand.

PSGIMAG versus PSG

Although PSGIMAG is similar to PSG, the following differences exist:

The FRONTPIX (Number of Front Pixels) parameter has been added to allow foreground pixel magnification, providing more realistic renderings.
PSGIMAG uses more memory than PSG.

In general, PSGIMAG is a more versatile function and generates better images than PSG, but it requires more memory and is slower.

PSGIMAG is capable of generating perspectives similar in quality and look to the interactive fly-through application FLY!.

Memory usage

PSGIMAG is CPU- and memory-intensive.

Memory is allocated dynamically, depending on the dimensions of the input data and the output scene generated. Using very large data sets can easily overload the available RAM on the host computer system, which can result in extremely poor performance or even function failure.

The amount of RAM required can be calculated as the sum of a through c, as shown below:

    a) to hold input imagery =  7 * fileXsize * fileYsize
    b) to hold output scene  =  7 * DBOW(3)   * DBOW(4)
    c) to hold the largest (optional) vector segment
       (sizes here can be difficult to determine)

    Input Imagery       Output Scene      Total RAM Used

    7*( 512 *  512)  +  7*( 512 *  512)  =    3.5 Mbytes
    7*(1024 * 1024)  +  7*( 512 *  512)  =    8.7 Mbytes
    7*(2048 * 2048)  +  7*( 512 *  512)  =   30.0 Mbytes
    7*(4096 * 4096)  +  7*(1024 * 2048)  =  126.0 Mbytes

Camera notes

This section provides background information about the camera model used to generate the perspective.

The view point (VPOINT) used in PSGIMAG is not the actual eye point, but the center of the bottom edge of the camera image plane. The actual eye point is some distance behind the camera image plane. This distance is determined by a calculation based on the field of view (VFIELD) and the number of foreground pixels (FRONTPIX).

Known issues

PSGIMAG is internally quite complex and there are a number of situations which could generate unexpected or poor results:

Elevation values should be `reasonable'. Extreme values (those outside the range -1,000 to 10,000 meters) may cause problems.
Clipping of vectors at boundaries of the database (and over background elevation areas) is poor; lines may not always extend right to the edge of the rendered image.
Specifying a viewpoint extremely far away from the data area, looking at data from underneath, or looking straight down while using a viewcone (tilt angle of 90, field-of-view angle greater than 0) may provide unexpected results.
The edges of the rendered areas are made by extending a line to zero elevation or 200 meters below the lowest elevation if the lowest elevation is less than 200 meters. This may produce unattractively deep edges if the image has very high elevations.

Examples

The user wishes to generate a perspective using the irvine.pix data set. The first step is to prepare the data set. Three new channels are created in irvine.pix to store the LUT-enhanced image we will use to generate the perspective. Three additional channels will store the output perspective image.

from pci.pcimod import pcimod

file='eltoro.pix'
pciop='ADD'
pcival=[6]                     #Add six 8-bit channels

pcimod(file,pciop,pcival)

The next step is to enhance the imagery. A true color image can be generated from channels 3, 2, and 1. LUTs previously saved in segments 4, 3, and 2 are used to enhance the raw data. Save the enhanced imagery to channels 10, 11, and 12.

from pci.lut import lut

file  = "irvine.pix"
dbic  = [3,2,1]     #Use input image channel 3,2,1
dblut = [4,3,2]     #Using LUT segment 4,3,2
dboc  = [10,11,12]  #Receive generated perspective scene


lut (file, dbic, dblut=dblut, dboc=dboc, filo=file)

The user draws a diagram of the database and determines the viewing position and viewing angle, as shown below.


+-----------------------+
|                       |
|                       |
|                       |               0
|                       |               |
|                       |               |
|                       |       270 ----+---- 90
|       /               |               |
|      /                |               |
|     X                 |              180
|                       |
+-----------------------+

Because irvine.pix is 512 by 512 in size, the user estimates the viewing position as approximately (150x, 400y), and a viewing angle of 45 degrees. Channel 16 on the modified irvine.pix contains elevation data in meters. Segments 25 and 26 contain vectors representing roads and streams, which the user wishes to drape over the rendered image. Output is to three empty channels of irvine.pix.

from pci.psgimag import psgimag

fili = 'irvine.pix'
dbic = [10,11,12]
dbec = [16]                    #Elevation Channel
escale = []
filo = 'irvine.pix'
dboc = [13,14,15]
backcol = [100,100,255]        #Background colors,Light Blue Sky
edgecol = [0,0,0]              #Edge colors
dbow    = []
vpoint  = [50,450]             #View Point
vfield  = [40]                 #Field of View Angle 30 degre
vangle  = [45,30]              #View Angle (direction,inclination) in degree
frontpix = [64]                #/Number of Pixel in the front
dbvs     = [25,26,26]
backelev = []

psgimag(fili, dbic, dbec, escale, filo, dboc, backcol, edgecol,
        dbow, vpoint, vfield, vangle, frontpix, dbvs, backelev)

After viewing the results, the user decides to exaggerate the elevations in the image by a factor of 2 and try again:

from pci.psgimag import psgimag

escale = [2.0,0]     #Elevation Scale and Offset

psgimag(fili, dbic, dbec, escale, filo, dboc, backcol, edgecol,
        dbow, vpoint, vfield, vangle, frontpix, dbvs, backelev)

In the final view, the user wants to see a special case: the parallel view (that is, a view with no perspective). FRONTPIX is set to the size of the database to provide an overview of the entire database.

from pci.psgimag import psgimag

vfield = [0]     #View Field
vpoint = [1,512] #View Point
frontpix = [512] #Number of Front Pixel

psgimag(fili, dbic, dbec, escale, filo, dboc, backcol, edgecol,
        dbow, vpoint, vfield, vangle, frontpix, dbvs, backelev)

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