no.petroware.logio.las

Class LasFileReader

java.lang.Object

no.petroware.logio.las.LasFileReader

public final class LasFileReader
extends Object

Class for reading LAS files.

Typical usage:

   LasFileReader reader = new LasFileReader(new File("/path/to/file.LAS"));
   List<LasFile> lasFiles = reader.read();
   

The method always returns a list of LasFile instances in case the disk file contains multiple logical files in sequence.

This class supports all versions of the LAS format.

Author:

Petroware AS

See Also:

LAS 3.0 Specification

Constructor Summary

Constructors

Constructor and Description
LasFileReader(File file) Create a LAS file reader for the specified disk file, using default character encoding (ISO 8859-1).
LasFileReader(File file, Charset characterEncoding) Create a LAS file reader for the specified disk file.
LasFileReader(InputStream inputStream) Create a LAS file reader for the specified stream, using default character encoding (ISO 8859-1).
LasFileReader(InputStream inputStream, Charset characterEncoding) Create a LAS file reader for the specified stream.

Method Summary

Modifier and Type	Method and Description
List<LasMessage>	getMessages() Return messages related to the previous LAS file read operation.
static Charset	guessEncoding(File file) Guess text encoding of the specified file.
static double	isLasFile(File file, byte[] content) Get the probability that the specified file is a LAS file.
List<LasFile>	read() Read the disk file and return the associated LasFile instances.
List<LasFile>	read(boolean shouldReadCurveData) Read the disk file and return the associated LasFile instances.
List<LasFile>	read(boolean shouldReadCurveData, boolean shouldCaptureStatistics) Read the disk file and return the associated LasFile instances.
List<LasFile>	read(boolean shouldReadCurveData, boolean shouldCaptureStatistics, LasDataListener dataListener) Read the disk file and return the associated LasFile instances.
void	readData(List<LasFile> lasFiles, boolean shouldCaptureStatistics, LasDataListener dataListener) Read data from a set of LAS files where the metadata has already been read.

Methods inherited from class java.lang.Object

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

Constructor Detail

LasFileReader

public LasFileReader(InputStream inputStream,
                     Charset characterEncoding)

Create a LAS file reader for the specified stream.

Parameters:

inputStream - Stream to read. Non-null.

characterEncoding - Character encoding to use during read. Typically UTF-8, US_ASCII or ISO 8859-1. Non-null.

Throws:

IllegalArgumentException - If inputStream or characterEncoding is null.

See Also:

guessEncoding(java.io.File)

LasFileReader

public LasFileReader(File file,
                     Charset characterEncoding)

Create a LAS file reader for the specified disk file.

Parameters:

file - Disk file to read. Non-null.

characterEncoding - Character encoding to use during read. Typically UTF-8, US_ASCII or ISO 8859-1. Non-null.

Throws:

IllegalArgumentException - If file or characterEncoding is null.

See Also:

guessEncoding(java.io.File)

LasFileReader

public LasFileReader(InputStream inputStream)

Create a LAS file reader for the specified stream, using default character encoding (ISO 8859-1).

Parameters:

inputStream - Input stream to read. Non-null.

Throws:

IllegalArgumentException - If inputStream is null.

LasFileReader

public LasFileReader(File file)

Create a LAS file reader for the specified disk file, using default character encoding (ISO 8859-1).

Parameters:

file - Disk file to read. Non-null.

Throws:

IllegalArgumentException - If file is null.

Method Detail

isLasFile

public static double isLasFile(File file,
                               byte[] content)

Get the probability that the specified file is a LAS file.

The check can be done with or without considering the content of the file. In the latter case, only the file name (typically its extension) is considered. In the former case a portion from the start of the file is used to match for known patterns. By passing the portion as an argument, the client code can read this once and then pass it to different classifiers in order to determine its most likely type.

Getting a portion of a file can be done by:

   File file = ...;
   BufferedInputStream stream = new BufferedInputStream(new FileInputStream(file));
   byte[] content = new byte[2000];
   stream.read(content, 0, content.length);
   stream.close();
   

Parameters:

file - File to check. Null to classify on content only.

content - A number of bytes from the start of the file. Null to classify on file name only.

Returns:

Probability that the file is a LAS file. [0.0,1.0].

guessEncoding

public static Charset guessEncoding(File file)

Guess text encoding of the specified file.

LAS files are supposed to be encoded as US-ASCII (7 bit ASCII), but are commonly encoded differently to accommodate for meta-data using language specific characters. Such meta-data will end up wrong (typically containing replacement characters often rendered as "?" in output) if read by the standard encoding.

This method will distinguish between US-ASCII, UTF8 or 8-bit ASCII (ISO 8859-1) and does not detect more esoteric encodings like UTF16 etc.

Parameters:

file - File to check. Non-null.

Returns:

The most probable encoding of the file. Returns ISO 8859-1 if not specifically detected as US_ASCII or UTF8. Never null.

Throws:

IllegalArgumentException - If file is null.

getMessages

public List<LasMessage> getMessages()

Return messages related to the previous LAS file read operation.

Returns:

List of messages associated with the read operation. Never null.

read

public List<LasFile> read(boolean shouldReadCurveData,
                          boolean shouldCaptureStatistics)
                   throws IOException

Read the disk file and return the associated LasFile instances.

Parameters:

shouldReadCurveData - True to indicates that bulk data should be read. Otherwise curves will be created, but not populated.

shouldCaptureStatistics - True to capture statistics per curve. Statistics capture will reduce read performance slightly, so set this to false if the statistics are not needed.

Returns:

All the logical LasFile instances read.

Throws:

IOException - If the read operation fails for some reason.

IllegalStateException - If a depth step has more or fewer values than the number of curves in wrapped mode.

See Also:

LasCurve.getStatistics()

readData

public void readData(List<LasFile> lasFiles,
                     boolean shouldCaptureStatistics,
                     LasDataListener dataListener)
              throws IOException,
                     InterruptedException

Read data from a set of LAS files where the metadata has already been read. This will preserve the existing LasFile structure in case a LAS file is read in two operations:

   // Read metadata
   List<LasFile> lasFiles = reader.read(false, ...);

   // Read the curve data
   reader.readData(lasFiles, ...);
   

There is nothing to gain in performance with this approach so in case the result is not cached, the following will be equivalent:

   // Read metadata
   List<LasFile> lasFiles = reader.read(false, ...);

   // Read all the data
   lasFiles = reader.read(true, ...);
   

Parameters:

lasFiles - The LAS files to populate. These must be the exact same list as retrieved by calling the #read(false,...) on the same LasFileReader instance. Otherwise the behavior is unpredictable.

shouldCaptureStatistics - True to capture statistics per curve during read. Statistics capture will reduce read performance slightly, so set this to false if the statistics are not needed.

dataListener - Listener that will be notified when new data has been read. Null if not used.

Throws:

IllegalArgumentException - If lasFiles is null.

IOException - If the read operation fails for some reason.

InterruptedException - If the client returns false from the LasDataListener.dataRead(no.petroware.logio.las.LasSection, no.petroware.logio.las.LasFile) method.

IllegalStateException - If a depth step has more or fewer values than the number of curves in wrapped mode.

read

public List<LasFile> read(boolean shouldReadCurveData,
                          boolean shouldCaptureStatistics,
                          LasDataListener dataListener)
                   throws IOException,
                          InterruptedException

Read the disk file and return the associated LasFile instances.

Parameters:

shouldReadCurveData - True to indicates that bulk data should be read. Otherwise curves will be created, but not populated.

shouldCaptureStatistics - True to capture statistics per curve. Statistics capture will reduce read performance slightly, so set this to false if the statistics are not needed.

dataListener - Client data listener. Null if not used.

Returns:

All the logical LasFile instances read.

Throws:

IOException - If the read operation fails for some reason.

InterruptedException - If the data listener cancels the operation.

IllegalStateException - If a depth step has more or fewer values than the number of curves in wrapped mode.

See Also:

LasCurve.getStatistics()

read

public List<LasFile> read(boolean shouldReadCurveData)
                   throws IOException

Read the disk file and return the associated LasFile instances. Do not capture overall statistics for each curve. This is equivalent of calling read(shouldReadCurveData, false).

Parameters:

shouldReadCurveData - Indicate if curve data should be read. False to read header data only.

Returns:

All the logical LasFile instances read.

Throws:

IOException - If the read operation fails for some reason.

IllegalStateException - If a depth step has more or fewer values than the number of curves in wrapped mode.

See Also:

read(boolean,boolean)

read

public List<LasFile> read()
                   throws IOException

Read the disk file and return the associated LasFile instances. Include curve data, but do not capture overall statistics for each curve. This is equivalent of calling read(true, false).

Returns:

All the logical LasFile instances read.

Throws:

IOException - If the read operation fails for some reason.

IllegalStateException - If a depth step has more or fewer values than the number of curves in wrapped mode.

See Also:

read(boolean,boolean)