mosaic Documentation

mosaic - Mosaic cubes

MOSAIC merges an input cube with an output mosaic cube. This can be done
in three ways.  The first method mosaics all bands (including back
planes) from the input cube into the corresponding bands in the output
cube.  MOSAIC checks the BAND_BIN_CENTER(wavelength) keyword in the
labels to insure the input band is mosaicked into the correct output
band.  The entire cube is used, a subcube is not allowed unless the
output mosaic is being initialized.  The second method mosaics one band
from the input cube into the band given by OBAND in the output cube.
There is no checking of the BAND_BIN_CENTER keyword for this method.
The third method creates an average mosaic which instead of laying
images on top of or underneath the mosaic averages the pixels of the
images put into the mosaic.  This method is implemented by setting
AVERAGE=YES.  See the parameters AVERAGE and LAST for more information.

Part of the requirement of mosaicking an input cube with a mosaic cube
is to define where in the mosaic cube the input cube is to be placed.
There are three ways, specified by the OPTION parameter, to define the
position of the input cube.

If OPTION=RECT, then the position of the input cube in the mosaic cube
is defined by rectangular coordinates.  The parameters SLM, starting
line position, and SSM, starting sample position, are used to define
where the upper-left corner of the input cube is to be positioned
spatially in the mosaic cube.  For example, if SLM=101 and SSM=307 then
the upper left corner of the specified input cube will be positioned at
line 101, sample 307 in the mosaic cube.  MOSAIC will determine which
output band from the BAND_BIN_CENTER keyword in the labels.  For more
details on mosaicking with the OPTION=RECT parameter, consult the
parameters SFROM, SSM, SLM.

If OPTION=MAP, then the position of the input cube in the mosaic cube is
specified by mapping label parameters found in both the input cube and
mosaic cube.  This option requires that the mosaic cube and the input
cube have the same mapping parameters including the same scale, center
latitude and longitude, standard parallels and other mapping parameters.
Except for the latitude and longitude ranges, the first cube put into a
mosaic defines the mapping parameters of the mosaic cube.  The latitude
and longitude ranges of a mosaic cube are specified by the LAT and LON
parameters.  For more information on mosaicking with the OPTION=MAP
parameter, consult the parameters LAT, LON, and OUTPNT.

If OPTION=TVREG, then the position of the input cube in the mosaic cube
is defined by a file which was created by the TVREG display program.
The TVREG program allows a user to interactively select where the input
cube is to be placed in the mosaic cube.  For more details on mosaicking
with the OPTION=TVREG parameter, consult the parameter TVREG, and the
TVREG display program documentation.

If TOP=YES, and MOSALL=NO, MOSAIC will overlay the input values over the
mosaic values.  The chart below describes how the special pixel values
are handled.  The left side indicates the input values the bar across
the top indicates the output mosaic value, and the "I" or "M" within the
chart indicates whether the input value or the mosaic value is used in
the output mosaic.

Low_I = Low instrument saturation
Low_R = Low representation saturation
High_I = High instrument saturation
High_R = High representation saturation
(** NOTE ** See $ISISINC/special_pixel.inc for the special pixel values)

                         Mosaic (M)
Input (I) | Valid |  Null | Low_I | Low_R | High_I | High_R
------------------------------------------------------------
  Valid   |   I   |   I   |   I   |   I   |    I   |    I   |
------------------------------------------------------------
  Null    |   M   |   I   |   M   |   M   |    M   |    M   |
------------------------------------------------------------
  Low_I   |   M   |   I   |   I   |   I   |    I   |    I   |
------------------------------------------------------------
  Low_R   |   M   |   I   |   I   |   I   |    I   |    I   |
------------------------------------------------------------
  High_I  |   M   |   I   |   I   |   I   |    I   |    I   |
------------------------------------------------------------
  High_R  |   M   |   I   |   I   |   I   |    I   |    I   |
------------------------------------------------------------

If TOP=NO, MOSAIC will put the input data underneath the mosaic so that
the only data which will show from the input cube will be where the
corresponding data in the mosaic area is a special pixel value.  The
chart below shows in detail how the special pixel values are handled.

                         Mosaic (M)
Input (I) | Valid |  Null | Low_I | Low_R | High_I | High_R
------------------------------------------------------------
  Valid   |   M   |   I   |   I   |   I   |    I   |    I   |
------------------------------------------------------------
  Null    |   M   |   M   |   M   |   M   |    M   |    M   |
------------------------------------------------------------
  Low_I   |   M   |   I   |   M   |   M   |    M   |    M   |
------------------------------------------------------------
  Low_R   |   M   |   I   |   M   |   M   |    M   |    M   |
------------------------------------------------------------
  High_I  |   M   |   I   |   M   |   M   |    M   |    M   |
------------------------------------------------------------
  High_R  |   M   |   I   |   M   |   M   |    M   |    M   |
------------------------------------------------------------


If TOP=NO, MOSALL will always be set to NO.

PROGRAMMER: Tracie Sucharski

Input cube file name
(Default extension is .cub)

NONE

Input subcube specifier

--

Output mosaic cube file
(Default extension is .cub)

NONE

Output band number

--

Check the BAND_BIN_CENTER
keyword in the input cube
and output mosaic to find
a match in the band dimention.
(YES, NO)

YES

Disable processing history text
(YES, NO)

NO

Convert input pixel type to
output pixel type
(YES, NO)

NO

Mosaic positioning option
(RECT,MAP,TVREG)

MAP

Average the images
(YES, NO)

NO

Last image to average
(YES, NO)

----------------------------

NO

Use if OPTION=RECT:
Starting line in mosaic

0

Starting sample in mosaic

0

Use if OPTION=TVREG:
TVREG data file name
----------------------------

" "

Put input image on top of the
mosaic (YES,NO)

YES

NO=Perform standard mosaic
YES=Mosaic null data as well

NO

NO=Perform standard mosaic
YES=Mosaic low and high sat
    values

NO

Create output mosaic
(YES,NO)

----------------------------

Use the following parameters
only if INIT=YES:

NO

Number of images in final
mosaic

-----------------------------

Use the following parameters
only if INIT=YES and OPTION=MAP:

50

Latitude range
(Default=Input cube)

0.,0.

Longitude range
(Default=Input cube)

     OR

0.,0.

Elevation range
(default=cube range)

0.,0.

Azimuth range
(default=cube range)

0.,0.

Lat,lon,line,samp (Use only
to change output translation
values)

-------------------------------

Use the following parameters
only if INIT=YES and OPTION=RECT

" "

Number of lines in mosaic

0

Number of samples in mosaic

0

Number of bands in mosaic

0

Backplane test
(RES,EMALO,EMAHI,INCLO,INCHI,
 MORPH,ALBEDO)

--

Propagate level 1 keyword
groups (ISIS_INSTRUMENT,
ISIS_GEOMETRY,ISIS_TARGET)
(YES,NO)

NO

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Input cube file name. If the file extension is omitted, then ".cub" will be assumed.
SFROM	SFROM specifies the subcube using a single string for all three dimensions of the cube. The order of the three dimensions is always "samples:lines:bands". If a dimension is left blank, all the data for that dimension is selected. The default value of NULL for SFROM selects the entire cube. Any application below can be used for any dimension. To select specific data from any dimension: "10-100(3):11,12,15-20:1-10(2)" = This example will select every third sample starting with sample 10 thru 100. It selects lines 11 and 12, and 15-20. It selects every other band, starting with band 1 thru 10. There are special characters that can be used for selecting a subcube efficiently, such as "*","#", and "~". For examples type "help sfrom" in TAE. **NOTE** For more examples and explanation of the many features of the SFROM parameter, tutor the sfrom.pdf or refer to Introduction To ISIS, Section 6, of the ISIS User's Manual **
TO	Output cube which contains the mosaic. It can either be created or one can be used which already exists. If INIT=Y then the program creates a cube of zeros. The size of the cube is determined by STO or by the latitude and longitude range and other mapping parameters on the input cube such as MAP_SCALE and MAP_PROJECTION_TYPE. The input cube will then be placed in the blank cube. If a cube already exists, then this cube is used and the input cube will be merged with this cube at the position indicated by SLM and SSM or at the position determined by the mapping parameters in the image labels. The rest of the cube is unaffected.
OBAND	This is the band in the output mosaic cube that an individual band from the input cube will be mosaicked into. If this parameter is not NULL, then MOSAIC will not check the BAND_BIN_CENTER keyword to insure the that the input band is being mosaicked into the correct output band.
BANDCHK	If this is set MOSAIC will check the BAND_BIN_CENTER keyword of the input cube and output mosaic cube to find the correct output band to mosaic the input band into. This will work even if the input cube does not have the same number of bands as the output cube. If this is turned off, MOSAIC assumes a one to one correspondence in the band dimension between the input cube and the mosaic cube. The input cube and the output mosaic must have the same number of bands if BANDCHK=NO. In other words band 1 of the input cube will be mosaicked into band 1 of the mosaic cube and so on up to the nth band.
HIST	Disable the processing history text. This will improve the efficiency if a large mosaic is being created.
CONV	If this is set and the pixel type of the input cube is different from the output mosaic cube, MOSAIC will convert the input cube to the output cube's pixel type. Use this option with caution.
OPTION	If OPTION=MAP, the mapping parameters from the labels are used to position input cube. If OPTION=RECT, the SLM and SSM of where the input cube is to be placed in the mosaic must be entered. If OPTION=TVREG, a data file created by TVREG is used to position the input cube.
AVERAGE	If AVERAGE=YES, the images are averaged instead of overlayed or underlayed. A running sum of the images input to MOSAIC is kept and the average is done when the final image is input. You must set LAST=YES to complete the average. When LAST=YES, the standard deviation is stored in a backplane named, STANDARD_DEVIATION. The sums, counts, and sum of squares are also saved in backplanes so that you can add more images onto the mosaic after you have set LAST=YES. At this time, the input images must have only a single band in the core region. If the input images have backplanes they are not preserved. The processing of backplanes with this option will be added in the future.
LAST	This is only used when AVERAGE=YES. This tells MOSAIC that this is the last image to be put into the mosaic. The final output will be the average of all input images on a pixel by pixel basis and the standard deviation will be calculated and stored in the backplane, STANDARD_DEVIATION.
SLM	This parameter is used when OPTION=RECT. This is the starting line for the FROM cube to be placed on the TO cube. If SLM = 1 then the FROM cube would be placed at the top of the TO cube. The SLM can be negative, so that the FROM cube would start off the edge of the TO cube. For instance if SLM were -10 then the first 10 lines of the FROM cube would be cut off and line 11 would be the first line of the TO cube.
SSM	This parameter is used when OPTION=RECT. This is the starting sample for the FROM cube to be placed on the TO cube. If SSM = 1 then the FROM cube would be placed at the top of the TO cube. The SSM can be negative, so that the FROM cube would start off the edge of the TO cube. For instance if SSM were -10 then the first 10 samples of the FROM cube would be cut off and sample 11 would be the first sample of the TO cube.
TVREG	This parameter is used only if OPTION=TVREG. This is the name of a file that is created by the TVREG program that contains a line and sample in the input cube and the matching line and sample in the mosaic. This file is only used if there was a problem with the geometry of the input cube and the starting line and sample must be redefined. A file can be created with an editor if necessary. The format of the TVREG data file is: Line,Samp (of input cube), Line,Samp (of mosaic) (9X,I6,3X,I6,18X,I6,3X,I6)
TOP	This option specifies whether to put the FROM cube on top of the mosaic or underneath the mosaic. If TOP=Y, the program will overlay all non-empty pixels on top of the existing data in the mosaic cube. An empty pixel is one which is 0 DN for 8-bit data, the NULL value for 16-bit data, and the null flag (all bits on) for 32-bit real data. For example, if the FROM cube had a blank area around the outside of the actual data which was zeroes, then any data that was already in the TO cube would "show through" this blank area even though the FROM cube goes on top. NOTE: When TOP=N MOSALL will be set to "N".
MOSALL	This option will specify to mosaic null data as well as non-null data. Thus, with this option all of the data in the input cube, regardless of whether the data is null or not, is moved to the output cube. NOTE: When TOP=N, MOSALL will be set to "N".
MOSSAT	This option specifies whether mosaic will put LOW_REPR_SAT, LOW_INSTR_SAT, HIGH_REPR_SAT and HIGH_INSTR_SAT pixels from the input cube onto the mosaic cube. If MOSSAT=NO, then the standard mosaic rules outlined in the graphs in the general help hold true. If MOSSAT=YES, then any low and high sat values from the input cube will be overlayed onto the mosaic no matter what the mosaic pixel value is.
INIT	If INIT = Y, an output cube will be created called the name given in TO. The cube will be all zeros with the size of the output cube determined by NLM, NSM and NBAND or the output latitude and longitude range and the mapping parameters in the input cube. If INIT = N, it is assumed the TO cube already exists. When mosaicking a number of cubes, the first to be mosaicked should use INIT = Y to create a cube big enough to hold all the cubes in the mosaic. This can be done one of two ways. The first would initialize the output cube to have the spatial size indicated by NLM and NSM and the number of bands equal to the number of bands in the input cube. If you want to create a mosaic cube with more bands in the mosaic cube than in the input cube, you must use the Table File option. After intialization, TO will be the same, and INIT = N should be used for all the other cubes entered into the mosaic.
NIMGS	This is the number of input images which will make up the final mosaic. This is used to allocate enough room in the history object. If there is no room in the history object when mosaicking an input image, a warning will be issued indicating that no history entry for this image will be entered, but the image will be put into the mosaic.
NLM	This parameter is used only if INIT=Y. For OPTION=RECT or OPTION=TVREG, this defines the number of lines needed in the TO cube. This cube should be made big enough to hold all of the images to be mosaicked. For OPTION=MAP, this parameter will override the computed number of lines for the mosaic that is done during intialization. In the polar example give for OUTPNT below, if the image is in the upper left corner NLM can be used to cut down the number of lines in the mosaic.
NSM	This parameter is used only if INIT=Y. For OPTION=RECT or OPTION=TVREG, this defines the number of samples needed in the TO cube. This cube should be made big enough to hold all the images to be mosaicked. For OPTION=MAP, this parameter will override the computed number of samples for the mosaic that is done during intialization. In the polar example give for OUTPNT below, if the image is in the upper left corner NSM can be used to cut down the number of samples in the mosaic.
NBM	This parameter is used only if INIT=Y. This defines the number of bands needed in the TO cube. The default will intialize a mosaic cube with the same number of bands as the input cube. If you want the mosaic cube to have more bands than the input cube, you must use the Table File option.
LAT	This parameter is used only if OPTION=MAP and INIT=Y. Latitude range of the mosaic. The default will use the latitude range of the first input cube of the mosaic. The range should be large enough to include all of the cubes to be mosaicked. The valid range is -90. to 90. LAT is ignored if INIT=N.
LON	This parameter is used only if OPTION=MAP and INIT=Y. Longitude range of the mosaic. The default will use the longitude range of the first input cube of the mosaic. The range should be large enough to include all of the cubes to be mosaicked. The valid range is -360. to 360. LON is ignored if INIT=N.
EL	The default procedure is to automatically find the elevation and azimuth range of the cube. (zero=horizontal,-90=down)
AZ	See EL.
OUTPNT	This parameter is used only if OPTION=MAP and INIT=Y. It is used to change the LINE_PROJECTION_OFFSET and SAMPLE_PROJECTION_OFFSET of the mosaic during initialization. These keywords indicate the position of line 1, sample 1 relative to the projection origin. PROJ_TRANSLATION is calculated using the given latitude and longitude range. In some special cases a very large cube will be created that is mostly empty. For example: a polar stereographic mosaic that includes the pole but most of the cube is between 0. and 90. degrees longitude. Almost three fourths of that mosaic would be empty. OUTPNT can be used to redefine the position of line 1, sample 1 and make a smaller cube. The requested string must contain a latitude and longitude and the line and sample of where that latitude and longitude is to be placed. For example: OUTPNT="90.,0.,100,300" will place the pole at line 100, sample 300.
BACKCHK	This parameter will check values of resolution, emission angle and incidence angle to decide which pixel to keep (input cube or mosaic cube). The default will do no backplane testing. If BACKCHK=RES, the better resolution will be kept. If BACKCHK=EMALO, the lower emission angle will be kept. If BACKCHK=EMAHI, the higher emission angle will be kept. If BACKCHK=INCLO, the lower incidence angle will be kept. If BACKCHK=INCHI, the higher incidence angle will be kept. If BACKCHK=MORPH, the lower value of the equation: resolution/cos(emission angle) will be kept. If BACKCHK=ALBEDO, the lower value of the equation: resolution*[1/cos(emission angle)+1/cos(incidence angle)] will be kept. NOTE: Backplanes can be added to an image using the "geoback" program.
PROPLEV1	If INIT=YES, then the level 1 keyword groups (ISIS_INSTRUMENT, ISIS_GEOMETRY, ISIS_TARGET) will be propagated to the mosaic file if PROPLEV1=YES.
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.