com.ermapper.ecw
Class JNCSFile

java.lang.Object
  |
  +--com.ermapper.ecw.JNCSFile

All Implemented Interfaces:

JNCSProgressiveUpdate

Direct Known Subclasses:

JNCSRenderer

public class JNCSFile

extends java.lang.Object

implements JNCSProgressiveUpdate

The JNCSFile class is the lowest level interface between the Java lannguage and the native ECW code. It uses the JNI to acces the native libraries. It is the base class for all of the ECW file access in Java. It supports reading from a local disk or from an ECWP URL.

In addition, this class provides standard setView() and readLine() functionality. It is analagous to the NCSFile object in the C++ SDK.

This class looks for the native libraries in 3 ways: 1) On the default search path.

2) Add the path to the native libraries as a parameter to the virutal machien, of the form: -Djava.library.path=C:\Program Files\Earth Resource Mapping\Image Web Server\Client

2) Add an entry in the propery file "jncsclasses.properties" in the users home directory, of the form: clientDLLPath=C\:\\Program Files\\Earth Resource Mapping\\Image Web Server\\Client

If all these methods fail to resolve the ECW libraries, native ECW imagery will not be available.

Since:

ECW Java SDK 2.3

Field Summary

boolean	bIsOpen A flag to specify if a valid file is currently open.
double	cellIncrementX The cell increment in the X direction of the file.
double	cellIncrementY The cell increment in the Y direction of the file.
int	cellSizeUnits The cell units of the file.
double	compressionRate The compression rate of the file.
java.lang.String	datum The GDT datum of the file.
static int	ECW_CELL_UNITS_DEGREES Cell units for the ecw file are degrees, a latitude/longitude coordinate system.
static int	ECW_CELL_UNITS_FEET Cell units for the ecw file are feet (US).
static int	ECW_CELL_UNITS_INVALID Cell units for the ecw file are unknown
static int	ECW_CELL_UNITS_METERS Cell units for the ecw file are metric meters
java.lang.String	fileName The filename of the current open file.
int	height The height (Y dimension) of the file.
int	numBands The number of image bands in the file.
double	originX The X origin of the current open file.
double	originY The Y origin of the current open file.
protected JNCSProgressiveUpdate	progImageClient
boolean	progressive Flag indicating if the file was opened in progressive mode.
java.lang.String	projection The GDT projection of the file.
int	width The width (X dimension) of the file.

Constructor Summary

JNCSFile()
Constructor.

JNCSFile(java.lang.String fileName, boolean progressive)
Constructor.

Method Summary

void	addProgressiveUpdateListener(JNCSProgressiveUpdate listener) Inform the ECW file that a client wants progressive imagery and is ready to listen for updates.
void	close(boolean freeCache) Close an ecw file, and optionally free the image case.
JNCSWorldPoint	convertDatasetToWorld(int nDatasetX, int nDatasetY) Convert a dataset x,y point into a world coordinate.
JNCSDatasetPoint	convertWorldToDataset(double dWorldX, double dWorldY) Convert a world x,y coordinate into a dataset point.
protected void	finalize() Performs final cleanup when the object is destroyed.
java.lang.String	getLastErrorText(int errorNum) Return the last error from the file object.
static java.lang.String	getLibVersion() Get the version of the decompressoin library (currently native) used in this class.
short	getPercentComplete() Get the percent complete of the current setView() command.
int	open(java.lang.String fileName, boolean bProgressive) Opens an ECW file in progressive or static mode, from a URL or local file path.
int	readImageRGBA(int[] pRGBAImageArray, int width, int height) Read an image of into an RGBA data buffer.
int	readLineBGRA(int[] pRGBArray) Read a scanline of BGRA format data.
int	readLineBIL(double[] pRGBArray) Read a scanline of BIL format data.
int	readLineBIL(int[] pRGBArray) Read a scanline of BIL format data.
int	readLineRGBA(int[] pRGBArray) Read a scanline of RGBA format data.
void	refreshUpdate(int nWidth, int nHeight, double dWorldTLX, double dWorldTLY, double dWorldBRX, double dWorldBRY) This method gets called when imagery arrives from the network and the set view was in world coordinates.
void	refreshUpdate(int nWidth, int nHeight, int dDatasetTLX, int dDatasetTLY, int dDatasetBRX, int dDatasetBRY) This method gets called when imagery arrives from the network, and the set view was in dataset cells.
int	setView(int nBands, int[] nBandList, double dWorldTLX, double dWorldTLY, double dWorldBRX, double dWorldBRY, int nWidth, int nHeight) Set a file view, in world coordinates.
int	setView(int nBands, int[] nBandList, int nDatasetTLX, int nDatasetTLY, int nDatasetBRX, int nDatasetBRY, int nWidth, int nHeight) Set a file view, in dataset coordinates.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ECW_CELL_UNITS_INVALID

public static final int ECW_CELL_UNITS_INVALID

Cell units for the ecw file are unknown

ECW_CELL_UNITS_METERS

public static final int ECW_CELL_UNITS_METERS

Cell units for the ecw file are metric meters

ECW_CELL_UNITS_DEGREES

public static final int ECW_CELL_UNITS_DEGREES

Cell units for the ecw file are degrees, a latitude/longitude coordinate system.

ECW_CELL_UNITS_FEET

public static final int ECW_CELL_UNITS_FEET

Cell units for the ecw file are feet (US).

numBands

public int numBands

The number of image bands in the file.

width

public int width

The width (X dimension) of the file.

height

public int height

The height (Y dimension) of the file.

originX

public double originX

The X origin of the current open file.

originY

public double originY

The Y origin of the current open file.

cellIncrementX

public double cellIncrementX

The cell increment in the X direction of the file.

cellIncrementY

public double cellIncrementY

The cell increment in the Y direction of the file.

cellSizeUnits

public int cellSizeUnits

The cell units of the file.

compressionRate

public double compressionRate

The compression rate of the file.

progressive

public boolean progressive

Flag indicating if the file was opened in progressive mode.

fileName

public java.lang.String fileName

The filename of the current open file.

datum

public java.lang.String datum

The GDT datum of the file.

projection

public java.lang.String projection

The GDT projection of the file.

bIsOpen

public boolean bIsOpen

A flag to specify if a valid file is currently open.

progImageClient

protected JNCSProgressiveUpdate progImageClient

Constructor Detail

JNCSFile

public JNCSFile()
         throws JNCSException

Constructor. Creates a default JNCSFile object

See Also:

JNCSFile(String, boolean)

JNCSFile

public JNCSFile(java.lang.String fileName,
                boolean progressive)
         throws JNCSException

Constructor. Creates a JNCSFile object and opens the file given by fileName. This is the same as calling the default constructor and then the open method.

See Also:

JNCSFile(), open(java.lang.String, boolean)

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Performs final cleanup when the object is destroyed.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable -

See Also:

JNCSFile()

open

public int open(java.lang.String fileName,
                boolean bProgressive)
         throws JNCSFileOpenFailedException

Opens an ECW file in progressive or static mode, from a URL or local file path. Currently, the JNI is used to communicate with the native ECW dll's, so this class is Win32 specific at this point in time (or until such a time that the libraries are ported to other platforms).

Parameters:

fileName - The file path

progressive - Progressive or static mode

Returns:

int 0 for success, any other number for failure.

Throws:

JNCSFileOpenFailedException - indicating that the file could not be opened. Use the getMessage() method of this Exception to determine the reason for the failure.

See Also:

close(boolean)

close

public void close(boolean freeCache)

Close an ecw file, and optionally free the image case.

Parameters:

freeCache - If true, the connection is closed and the image cache is freed. If false the connection is kept alive, pending requests are cancelled, but the image cache is left intact.

Returns:

none

See Also:

open(java.lang.String, boolean)

addProgressiveUpdateListener

public void addProgressiveUpdateListener(JNCSProgressiveUpdate listener)

Inform the ECW file that a client wants progressive imagery and is ready to listen for updates.

Parameters:

listener - The client that implements the JNCSProgressiveUpdate interface

Returns:

none

See Also:

JNCSProgressiveUpdate.refreshUpdate(int, int, double, double, double, double)

refreshUpdate

public void refreshUpdate(int nWidth,
                          int nHeight,
                          double dWorldTLX,
                          double dWorldTLY,
                          double dWorldBRX,
                          double dWorldBRY)

Description copied from interface: JNCSProgressiveUpdate

This method gets called when imagery arrives from the network and the set view was in world coordinates. When using progressive imagery, clients must implement this class.

Specified by:

refreshUpdate in interface JNCSProgressiveUpdate

Following copied from interface: com.ermapper.ecw.JNCSProgressiveUpdate

Parameters:

nWidth - The width of the setView which generated this callback

nHeight - The height of the setView which generated this callback

dWorldTLX - The top left X coord that generated this callback

dWorldTLY - The top left Y coord that generated this callback

dWorldBRX - The bottom right X coord that generated this callback

dWorldBRY - The bottom right Y coord that generated this callback

See Also:

addProgressiveUpdateListener(com.ermapper.ecw.JNCSProgressiveUpdate)

refreshUpdate

public void refreshUpdate(int nWidth,
                          int nHeight,
                          int dDatasetTLX,
                          int dDatasetTLY,
                          int dDatasetBRX,
                          int dDatasetBRY)

Description copied from interface: JNCSProgressiveUpdate

This method gets called when imagery arrives from the network, and the set view was in dataset cells. When using progressive imagery, clients must implement this class.

Specified by:

refreshUpdate in interface JNCSProgressiveUpdate

Following copied from interface: com.ermapper.ecw.JNCSProgressiveUpdate

Parameters:

nWidth - The width of the setView which generated this callback

nHeight - The height of the setView which generated this callback

dDatasetTLX - The top left X dataset cell that generated this callback

dDatasetTLY - The top left Y dataset cell that generated this callback

dDatasetBRX - The bottom right X dataset cell that generated this callback

dDatasetBRY - The bottom right Y dataset cell that generated this callback

See Also:

addProgressiveUpdateListener(com.ermapper.ecw.JNCSProgressiveUpdate)

setView

public int setView(int nBands,
                   int[] nBandList,
                   int nDatasetTLX,
                   int nDatasetTLY,
                   int nDatasetBRX,
                   int nDatasetBRY,
                   int nWidth,
                   int nHeight)
            throws JNCSInvalidSetViewException,
                   JNCSFileNotOpenException

Set a file view, in dataset coordinates. The intput dataset cells must lie within the extents of the file. If they do not an JNCSInvalidSetViewException is thrown. For example, to view the entire file, input top left coordinates of (0,0) and bottom right coordinates of (width-1, height-1) must be used.

Parameters:

nBands - The number of bands to be output

nBansList - The bandlist

nDatasetTLX - Top left X in dataset coordinates

nDatasetTLY - Top left Y in dataset coordinates

nDatasetBRX - Bottom right X in dataset coordinates

nDatasetBRY - Bottom right Y in dataset coordinates

nWidth - Output view width

nHeight - Output view height

Returns:

int 0 for success, any other number, failure

Throws:

JNCSInvalidSetViewException - indicating that the parameters passed to setView where incorrect.

JNCSFileNotOpenException - indicating that there is no current valid file open.

See Also:

setView(int, int[], double, double, double, double, int, int)

setView

public int setView(int nBands,
                   int[] nBandList,
                   double dWorldTLX,
                   double dWorldTLY,
                   double dWorldBRX,
                   double dWorldBRY,
                   int nWidth,
                   int nHeight)
            throws JNCSInvalidSetViewException,
                   JNCSFileNotOpenException

Set a file view, in world coordinates. The world coordinates must be in the same space as the datum and projection of the file. No coordinate checking is performed. If the coordinates do not convert correctly to a cell within the dataset, a JNCSInvalidSetViewException is thrown. For example, to view the entire file, top left input coordinates of (originX, originY) and bottom right coordinates of (originX + (cellIncrementX*width), originY + (cellIncrementY*height)) must be used.

Parameters:

nBands - The number of bands to be output

nBansList - The bandlist

dWorldTLX - Top left X in world coordinates

dWorldTLY - Top left Y in world coordinates

dWorldBRX - Bottom right X in world coordinates

dWorldBRY - Bottom right Y in world coordinates

nWidth - Output view width

nHeight - Output view height

Returns:

int 0 for success, any other number, failure

Throws:

JNCSInvalidSetViewException - indicating that the parameters passed to setView where incorrect.

JNCSFileNotOpenException - indicating that there is no current valid file open.

See Also:

setView(int, int[], int, int, int, int, int, int)

readLineRGBA

public int readLineRGBA(int[] pRGBArray)
                 throws JNCSException

Read a scanline of RGBA format data.

Parameters:

pRGBArray - The input array which should be of dimension nWidth.

Returns:

An integer which will be an error number if an exception occurs.

Throws:

JNCSException - indicating there was an error in the read process.

See Also:

setView(int, int[], int, int, int, int, int, int), getLastErrorText(int), readLineBGRA(int[]), readLineBIL(int[])

readLineBGRA

public int readLineBGRA(int[] pRGBArray)
                 throws JNCSException

Read a scanline of BGRA format data. This is currently not implemented.

Parameters:

PARAMETER - DESCRIPTION

Returns:

An integer which will be an error number if an exception occurs.

Throws:

JNCSException - indicating there was an error in the read process.

See Also:

setView(int, int[], int, int, int, int, int, int), getLastErrorText(int), readLineRGBA(int[]), readLineBIL(int[])

readLineBIL

public int readLineBIL(int[] pRGBArray)
                throws JNCSException

Read a scanline of BIL format data. This is currently not implemented.

Parameters:

PARAMETER - DESCRIPTION

Returns:

An integer which will be an error number if an exception occurs.

Throws:

JNCSException - indicating there was an error in the read process.

See Also:

setView(int, int[], int, int, int, int, int, int), getLastErrorText(int), com.ermapper.ecw.JNCSFile#readLineRGB, readLineRGBA(int[]), com.ermapper.ecw.JNCSFile#readLineBGR, readLineBGRA(int[])

readLineBIL

public int readLineBIL(double[] pRGBArray)
                throws JNCSException

Read a scanline of BIL format data. This is currently not implemented.

Parameters:

PARAMETER - DESCRIPTION

Returns:

An integer which will be an error number if an exception occurs.

Throws:

JNCSException - indicating there was an error in the read process.

See Also:

setView(int, int[], int, int, int, int, int, int), getLastErrorText(int), com.ermapper.ecw.JNCSFile#readLineRGB, readLineRGBA(int[]), com.ermapper.ecw.JNCSFile#readLineBGR, readLineBGRA(int[])

readImageRGBA

public int readImageRGBA(int[] pRGBAImageArray,
                         int width,
                         int height)
                  throws JNCSException

Read an image of into an RGBA data buffer.

Parameters:

pRGBAImageArray - An array of integer data, the size of which will be the width of the setView * height of the setView.

width - The width of the set view

height - The height of the set view

Returns:

An integer which will be an error number if an exception occurs.

Throws:

JNCSException - indicating there was an error in the read process.

See Also:

setView(int, int[], int, int, int, int, int, int), getLastErrorText(int), readLineBIL(int[])

getLastErrorText

public java.lang.String getLastErrorText(int errorNum)

Return the last error from the file object. If no error or exception has occured, the call returns an undefined result.

Parameters:

errorNum - The error number returned from a previous routine.

Returns:

A string representation of the error.

convertWorldToDataset

public JNCSDatasetPoint convertWorldToDataset(double dWorldX,
                                              double dWorldY)
                                       throws JNCSFileNotOpenException

Convert a world x,y coordinate into a dataset point. The conversion represents dataset cell. The cell does not necessarilly lie inside the bounds of the dataset however.

Parameters:

dWorldX - The input world x coordinate.

dWorldY - The input world y coordinate.

Returns:

A JNCSDatasetPoint representing the dataset cell.

Throws:

JNCSFileNotOpenException - indicating there is currently no valid open file.

See Also:

convertDatasetToWorld(int, int)

convertDatasetToWorld

public JNCSWorldPoint convertDatasetToWorld(int nDatasetX,
                                            int nDatasetY)
                                     throws JNCSFileNotOpenException

Convert a dataset x,y point into a world coordinate. The conversion represents a point in the coordinate system of the file.

Parameters:

nDatasetX - The input dataset x cell.

nDatasetY - The input dataset y cell

Returns:

A JNCSWorldPoint representing the world coordinate.

Throws:

JNCSFileNotOpenException - indicating there is currently no valid open file.

See Also:

convertWorldToDataset(double, double)

getPercentComplete

public short getPercentComplete()

Get the percent complete of the current setView() command. Only meaningfull in progressive mode.

Returns:

A percentage from 0 to 100.

See Also:

setView(int, int[], int, int, int, int, int, int)

getLibVersion

public static java.lang.String getLibVersion()

Get the version of the decompressoin library (currently native) used in this class. Note that this is not the file versio of the currently open file.

Returns:

A string representing the lib version, in the form "1,5,2,0"