loci.common

Class DataTools

java.lang.Object

loci.common.DataTools

public final class DataTools
extends Object

A utility class with convenience methods for reading, writing and decoding words.

Author:

Curtis Rueden ctrueden at wisc.edu, Chris Allan callan at blackcat.ca, Melissa Linkert melissa at glencoesoftware.com

Constructor Summary

Constructors

Modifier	Constructor and Description
private	DataTools()

Method Summary

Methods

Modifier and Type	Method and Description
static byte[]	allocate(int... sizes) Allocates a 1-dimensional byte array matching the product of the given sizes.
static double	bytesToDouble(byte[] bytes, boolean little) Translates up to the first 8 bytes of a byte array to a double.
static double	bytesToDouble(byte[] bytes, int off, boolean little) Translates up to the first 8 bytes of a byte array beyond the given offset to a double.
static double	bytesToDouble(byte[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to a double.
static double	bytesToDouble(short[] bytes, boolean little) Translates up to the first 8 bytes of a byte array to a double.
static double	bytesToDouble(short[] bytes, int off, boolean little) Translates up to the first 8 bytes of a byte array beyond the given offset to a double.
static double	bytesToDouble(short[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to a double.
static float	bytesToFloat(byte[] bytes, boolean little) Translates up to the first 4 bytes of a byte array to a float.
static float	bytesToFloat(byte[] bytes, int off, boolean little) Translates up to the first 4 bytes of a byte array beyond a given offset to a float.
static float	bytesToFloat(byte[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to a float.
static float	bytesToFloat(short[] bytes, boolean little) Translates up to the first 4 bytes of a byte array to a float.
static float	bytesToFloat(short[] bytes, int off, boolean little) Translates up to the first 4 bytes of a byte array beyond a given offset to a float.
static float	bytesToFloat(short[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond a given offset to a float.
static String	bytesToHex(byte[] b) Translates the given byte array into a String of hexadecimal digits.
static int	bytesToInt(byte[] bytes, boolean little) Translates up to the first 4 bytes of a byte array to an int.
static int	bytesToInt(byte[] bytes, int off, boolean little) Translates up to the first 4 bytes of a byte array beyond the given offset to an int.
static int	bytesToInt(byte[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to an int.
static int	bytesToInt(short[] bytes, boolean little) Translates up to the first 4 bytes of a byte array to an int.
static int	bytesToInt(short[] bytes, int off, boolean little) Translates up to the first 4 bytes of a byte array beyond the given offset to an int.
static int	bytesToInt(short[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to an int.
static long	bytesToLong(byte[] bytes, boolean little) Translates up to the first 8 bytes of a byte array to a long.
static long	bytesToLong(byte[] bytes, int off, boolean little) Translates up to the first 8 bytes of a byte array beyond the given offset to a long.
static long	bytesToLong(byte[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to a long.
static long	bytesToLong(short[] bytes, boolean little) Translates up to the first 8 bytes of a byte array to a long.
static long	bytesToLong(short[] bytes, int off, boolean little) Translates up to the first 8 bytes of a byte array beyond the given offset to a long.
static long	bytesToLong(short[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to a long.
static short	bytesToShort(byte[] bytes, boolean little) Translates up to the first 2 bytes of a byte array to a short.
static short	bytesToShort(byte[] bytes, int off, boolean little) Translates up to the first 2 bytes of a byte array beyond the given offset to a short.
static short	bytesToShort(byte[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array beyond the given offset to a short.
static short	bytesToShort(short[] bytes, boolean little) Translates up to the first 2 bytes of a byte array to a short.
static short	bytesToShort(short[] bytes, int off, boolean little) Translates up to the first 2 bytes of a byte array byond the given offset to a short.
static short	bytesToShort(short[] bytes, int off, int len, boolean little) Translates up to the first len bytes of a byte array byond the given offset to a short.
static boolean	containsValue(int[] array, int value) Returns true if the given value is contained in the given array.
static byte[]	doublesToBytes(double[] values, boolean little) Translates an array of double values into an array of byte values.
static byte[]	doubleToBytes(double value, boolean little) Translates the double value into an array of eight bytes.
static byte[]	floatsToBytes(float[] values, boolean little) Translates an array of float values into an array of byte values.
static byte[]	floatToBytes(float value, boolean little) Translates the float value into an array of four bytes.
static int	indexOf(int[] array, int value) Returns the index of the first occurrence of the given value in the given array.
static int	indexOf(Object[] array, Object value) Returns the index of the first occurrence of the given value in the given Object array.
static byte[]	intsToBytes(int[] values, boolean little) Translates an array of int values into an array of byte values.
static byte[]	intToBytes(int value, boolean little) Translates the int value into an array of four bytes.
static byte[]	longsToBytes(long[] values, boolean little) Translates an array of long values into an array of byte values.
static byte[]	longToBytes(long value, boolean little) Translates the long value into an array of eight bytes.
static Object	makeDataArray(byte[] b, int bpp, boolean fp, boolean little) Convert a byte array to the appropriate 1D primitive type array.
static Object	makeDataArray2D(byte[] b, int bpp, boolean fp, boolean little, int height) Convert a byte array to the appropriate 2D primitive type array.
static byte[]	makeSigned(byte[] b)
static int[]	makeSigned(int[] i)
static short[]	makeSigned(short[] s)
static double[]	normalizeDoubles(double[] data) Normalize the given double array so that the minimum value maps to 0.0 and the maximum value maps to 1.0.
static float[]	normalizeFloats(float[] data) Normalize the given float array so that the minimum value maps to 0.0 and the maximum value maps to 1.0.
static String	readFile(String id) Reads the contents of the given file into a string.
static int	safeMultiply32(int... sizes) Checks that the product of the given sizes does not exceed the 32-bit integer limit (i.e., Integer.MAX_VALUE).
static long	safeMultiply64(long... sizes) Checks that the product of the given sizes does not exceed the 64-bit integer limit (i.e., Long.MAX_VALUE).
static boolean	samePrefix(String s1, String s2) Check if two filenames have the same prefix.
static String	sanitize(String s) Remove unprintable characters from the given string.
static String	sanitizeDouble(String value) Normalize the decimal separator for the user's locale.
static byte[]	shortsToBytes(short[] values, boolean little) Translates an array of short values into an array of byte values.
static byte[]	shortToBytes(short value, boolean little) Translates the short value into an array of two bytes.
private static String	sizeAsProduct(int... sizes)
private static String	sizeAsProduct(long... sizes)
static String	stripString(String toStrip) Remove null bytes from a string.
static char	swap(char x)
static double	swap(double x)
static float	swap(float x)
static int	swap(int x)
static long	swap(long x)
static short	swap(short x)
static void	unpackBytes(long value, byte[] buf, int ndx, int nBytes, boolean little) Translates nBytes of the given long and places the result in the given byte array.
private static boolean	willOverflow(long v1, long v2)

Methods inherited from class java.lang.Object

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

Constructor Detail

DataTools

private DataTools()

Method Detail

readFile

public static String readFile(String id)
                       throws IOException

Reads the contents of the given file into a string.

Throws:

IOException

bytesToShort

public static short bytesToShort(byte[] bytes,
                 int off,
                 int len,
                 boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to a short. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToShort

public static short bytesToShort(byte[] bytes,
                 int off,
                 boolean little)

Translates up to the first 2 bytes of a byte array beyond the given offset to a short. If there are fewer than 2 bytes available the MSBs are all assumed to be zero (regardless of endianness).

bytesToShort

public static short bytesToShort(byte[] bytes,
                 boolean little)

Translates up to the first 2 bytes of a byte array to a short. If there are fewer than 2 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToShort

public static short bytesToShort(short[] bytes,
                 int off,
                 int len,
                 boolean little)

Translates up to the first len bytes of a byte array byond the given offset to a short. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToShort

public static short bytesToShort(short[] bytes,
                 int off,
                 boolean little)

Translates up to the first 2 bytes of a byte array byond the given offset to a short. If there are fewer than 2 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToShort

public static short bytesToShort(short[] bytes,
                 boolean little)

Translates up to the first 2 bytes of a byte array to a short. If there are fewer than 2 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToInt

public static int bytesToInt(byte[] bytes,
             int off,
             int len,
             boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to an int. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToInt

public static int bytesToInt(byte[] bytes,
             int off,
             boolean little)

Translates up to the first 4 bytes of a byte array beyond the given offset to an int. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToInt

public static int bytesToInt(byte[] bytes,
             boolean little)

Translates up to the first 4 bytes of a byte array to an int. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToInt

public static int bytesToInt(short[] bytes,
             int off,
             int len,
             boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to an int. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToInt

public static int bytesToInt(short[] bytes,
             int off,
             boolean little)

Translates up to the first 4 bytes of a byte array beyond the given offset to an int. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToInt

public static int bytesToInt(short[] bytes,
             boolean little)

Translates up to the first 4 bytes of a byte array to an int. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToFloat

public static float bytesToFloat(byte[] bytes,
                 int off,
                 int len,
                 boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to a float. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToFloat

public static float bytesToFloat(byte[] bytes,
                 int off,
                 boolean little)

Translates up to the first 4 bytes of a byte array beyond a given offset to a float. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToFloat

public static float bytesToFloat(byte[] bytes,
                 boolean little)

Translates up to the first 4 bytes of a byte array to a float. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToFloat

public static float bytesToFloat(short[] bytes,
                 int off,
                 int len,
                 boolean little)

Translates up to the first len bytes of a byte array beyond a given offset to a float. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToFloat

public static float bytesToFloat(short[] bytes,
                 int off,
                 boolean little)

Translates up to the first 4 bytes of a byte array beyond a given offset to a float. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToFloat

public static float bytesToFloat(short[] bytes,
                 boolean little)

Translates up to the first 4 bytes of a byte array to a float. If there are fewer than 4 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToLong

public static long bytesToLong(byte[] bytes,
               int off,
               int len,
               boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to a long. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToLong

public static long bytesToLong(byte[] bytes,
               int off,
               boolean little)

Translates up to the first 8 bytes of a byte array beyond the given offset to a long. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToLong

public static long bytesToLong(byte[] bytes,
               boolean little)

Translates up to the first 8 bytes of a byte array to a long. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToLong

public static long bytesToLong(short[] bytes,
               int off,
               int len,
               boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to a long. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToLong

public static long bytesToLong(short[] bytes,
               int off,
               boolean little)

Translates up to the first 8 bytes of a byte array beyond the given offset to a long. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToLong

public static long bytesToLong(short[] bytes,
               boolean little)

Translates up to the first 8 bytes of a byte array to a long. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToDouble

public static double bytesToDouble(byte[] bytes,
                   int off,
                   int len,
                   boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to a double. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToDouble

public static double bytesToDouble(byte[] bytes,
                   int off,
                   boolean little)

Translates up to the first 8 bytes of a byte array beyond the given offset to a double. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToDouble

public static double bytesToDouble(byte[] bytes,
                   boolean little)

Translates up to the first 8 bytes of a byte array to a double. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToDouble

public static double bytesToDouble(short[] bytes,
                   int off,
                   int len,
                   boolean little)

Translates up to the first len bytes of a byte array beyond the given offset to a double. If there are fewer than len bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToDouble

public static double bytesToDouble(short[] bytes,
                   int off,
                   boolean little)

Translates up to the first 8 bytes of a byte array beyond the given offset to a double. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToDouble

public static double bytesToDouble(short[] bytes,
                   boolean little)

Translates up to the first 8 bytes of a byte array to a double. If there are fewer than 8 bytes available, the MSBs are all assumed to be zero (regardless of endianness).

bytesToHex

public static String bytesToHex(byte[] b)

Translates the given byte array into a String of hexadecimal digits.

sanitizeDouble

public static String sanitizeDouble(String value)

Normalize the decimal separator for the user's locale.

shortToBytes

public static byte[] shortToBytes(short value,
                  boolean little)

Translates the short value into an array of two bytes.

intToBytes

public static byte[] intToBytes(int value,
                boolean little)

Translates the int value into an array of four bytes.

floatToBytes

public static byte[] floatToBytes(float value,
                  boolean little)

Translates the float value into an array of four bytes.

longToBytes

public static byte[] longToBytes(long value,
                 boolean little)

Translates the long value into an array of eight bytes.

doubleToBytes

public static byte[] doubleToBytes(double value,
                   boolean little)

Translates the double value into an array of eight bytes.

shortsToBytes

public static byte[] shortsToBytes(short[] values,
                   boolean little)

Translates an array of short values into an array of byte values.

intsToBytes

public static byte[] intsToBytes(int[] values,
                 boolean little)

Translates an array of int values into an array of byte values.

floatsToBytes

public static byte[] floatsToBytes(float[] values,
                   boolean little)

Translates an array of float values into an array of byte values.

longsToBytes

public static byte[] longsToBytes(long[] values,
                  boolean little)

Translates an array of long values into an array of byte values.

doublesToBytes

public static byte[] doublesToBytes(double[] values,
                    boolean little)

Translates an array of double values into an array of byte values.

unpackBytes

public static void unpackBytes(long value,
               byte[] buf,
               int ndx,
               int nBytes,
               boolean little)

Translates nBytes of the given long and places the result in the given byte array.

Throws:

IllegalArgumentException - if the specified indices fall outside the buffer

makeDataArray

public static Object makeDataArray(byte[] b,
                   int bpp,
                   boolean fp,
                   boolean little)

Convert a byte array to the appropriate 1D primitive type array.

Parameters:

b - Byte array to convert.

bpp - Denotes the number of bytes in the returned primitive type (e.g. if bpp == 2, we should return an array of type short).

fp - If set and bpp == 4 or bpp == 8, then return floats or doubles.

little - Whether byte array is in little-endian order.

makeDataArray2D

public static Object makeDataArray2D(byte[] b,
                     int bpp,
                     boolean fp,
                     boolean little,
                     int height)

Convert a byte array to the appropriate 2D primitive type array.

Parameters:

b - Byte array to convert.

bpp - Denotes the number of bytes in the returned primitive type (e.g. if bpp == 2, we should return an array of type short).

fp - If set and bpp == 4 or bpp == 8, then return floats or doubles.

little - Whether byte array is in little-endian order.

height - The height of the output primitive array (2nd dim length).

Returns:

a 2D primitive array of appropriate type, dimensioned [height][b.length / (bpp * height)]

Throws:

IllegalArgumentException - if input byte array does not divide evenly into height pieces

swap

public static short swap(short x)

swap

public static char swap(char x)

swap

public static int swap(int x)

swap

public static long swap(long x)

swap

public static float swap(float x)

swap

public static double swap(double x)

stripString

public static String stripString(String toStrip)

Remove null bytes from a string.

samePrefix

public static boolean samePrefix(String s1,
                 String s2)

Check if two filenames have the same prefix.

sanitize

public static String sanitize(String s)

Remove unprintable characters from the given string.

normalizeFloats

public static float[] normalizeFloats(float[] data)

Normalize the given float array so that the minimum value maps to 0.0 and the maximum value maps to 1.0.

normalizeDoubles

public static double[] normalizeDoubles(double[] data)

Normalize the given double array so that the minimum value maps to 0.0 and the maximum value maps to 1.0.

allocate

public static byte[] allocate(int... sizes)
                       throws IllegalArgumentException

Allocates a 1-dimensional byte array matching the product of the given sizes.

Parameters:

sizes - list of sizes from which to allocate the array

Returns:

a byte array of the appropriate size

Throws:

IllegalArgumentException - if the total size exceeds 2GB, which is the maximum size of an array in Java; or if any size argument is zero or negative

safeMultiply32

public static int safeMultiply32(int... sizes)
                          throws IllegalArgumentException

Checks that the product of the given sizes does not exceed the 32-bit integer limit (i.e., Integer.MAX_VALUE).

Parameters:

sizes - list of sizes from which to compute the product

Returns:

the product of the given sizes

Throws:

IllegalArgumentException - if the total size exceeds 2GiB, which is the maximum size of an int in Java; or if any size argument is zero or negative

safeMultiply64

public static long safeMultiply64(long... sizes)
                           throws IllegalArgumentException

Checks that the product of the given sizes does not exceed the 64-bit integer limit (i.e., Long.MAX_VALUE).

Parameters:

sizes - list of sizes from which to compute the product

Returns:

the product of the given sizes

Throws:

IllegalArgumentException - if the total size exceeds 8EiB, which is the maximum size of a long in Java; or if any size argument is zero or negative

containsValue

public static boolean containsValue(int[] array,
                    int value)

Returns true if the given value is contained in the given array.

indexOf

public static int indexOf(int[] array,
          int value)

Returns the index of the first occurrence of the given value in the given array. If the value is not in the array, returns -1.

indexOf

public static int indexOf(Object[] array,
          Object value)

Returns the index of the first occurrence of the given value in the given Object array. If the value is not in the array, returns -1.

makeSigned

public static byte[] makeSigned(byte[] b)

makeSigned

public static short[] makeSigned(short[] s)

makeSigned

public static int[] makeSigned(int[] i)

sizeAsProduct

private static String sizeAsProduct(int... sizes)

sizeAsProduct

private static String sizeAsProduct(long... sizes)

willOverflow

private static boolean willOverflow(long v1,
                   long v2)