videometer 0.0.28

Videometer python HIPS image reader and writer for Multispectral images

Videometer toolbox for Python

A toolbox for multispectral .HIPS images from Videometer A/S

Installation

System requirements:

• Windows operating system
• 64-bit Intel processor

Use the package manager pip to install

pip install videometer

Note : First time the videometer.hips is imported it will fetch DLLs

Usage - Read

videometer.hips.read(path, bandIndexesToUse=[])

   Reads a HIPS image and stores it as an ImageClass object.

   Parameters
      Input :
       - path <String>: Path to the image.
       - bandIndexesToUse <List of Ints> (optional) List of the indexes who are suppose to be in
             the returned ImageClass object. If empty then it will return all of them (default).

      Output :
       - ImageClass object

ImageClass is explained below.

Example

from videometer import hips

imageCls = hips.read("image.hips")

Usage - readOnlyPixelValues

videometer.hips.readOnlyPixelValues(path)

   Reads a HIPS image and returns pixel values in a 3-D Numpy array.
   Makes the reading quicker when only the pixel values are wanted.

   Parameters
      Input :
       - path <String>: Path to the image.

      Output :
       - 3-D Numpy array

Example

from videometer import hips

img = hips.readOnlyPixelValues("image.hips")

Usage - Write

videometer.hips.write(image, path, compression="SameAsImageClass", verbose=False)

   Writes a HIPS image from an ImageClass object or a NumPy array that corresponds
   to the pixel values of a spectral image.

   Parameters
      Input :
       - image <ImageClass OR 3-D NumPy array>: The image to write.
       - path <String>: path of the to be written HIPS file.
         Note it has to include the .hips extension and a existing folder structure.
       - compression <String>: Compression level of the image, same as in VideometerLab
          (Table can be seen below and more detailed one in VideometerLab under
         File > Preferences > Compression ) :

Level of Compression : {
    "SameAsImageClass" : Keep the same compression as is in the ImageClass 
                        (if it is a numpy array then it will be Uncompressed) 
    "Uncompressed" : No compression
                    (Same as Original in VideometerLab software),
    "VeryHighQuality" : (see VideometerLab software),
    "HighQuality" : (see VideometerLab software),
    "HighCompression" : (see VideometerLab software),
    "VeryHighCompression" : (see VideometerLab software)
}

       - verbose <Boolean>: If true then prints out the name of the file otherwise not.
          Default is false

      Output :
       - Returns a full path to the written .HIPS image if successful otherwise None.

Compression Preset Table

Preset	Storage	Reflectance Precision	Typical Image Size
Uncompressed	RAW (32bit float)	N/A	912MB (100%)
Very High Quality	12 bit PNG	0.03	171MB (19%)
High Quality	10 bit PNG	0.12	159MB (17%)
High Compression	8 bit PNG	0.47	110MB (10%)
Very High Compression	8 bit JPEG	0.47 + Edge artifacts	31MB (3%)

Example - Writing ImageClass

from videometer import hips

imageCls = hips.read("image.hips")
fullPath2Image = hips.write(imageCls,"image.hips",compression="HighCompression")

if fullPath2Image is None:
    print("FAILED")
else:
    print("SUCCESS!")

Example - Writing NumPy array

from videometer import hips
import numpy as np

npArray = np.array(
    [[0.,1.,2.],
    [3.,4.,5.],
    [6.,7.,8.]], dtype=np.float32)
npArray = npArray.reshape((3,3,1)) # Height, Width, Bands

fullPath2Image = hips.write(npArray,"imageFromNumpyArray.hips")

if fullPath2Image is None:
    print("Failed")
else:
    print("Success!")

Usage - Show

videometer.hips.show( image, ifUseMask=False, bandIndexesToUse=[], ifOnlyGetListOfPLTObjects=False):

   Function that shows images of individual bands.

   Parameters
      Input :
       - image <ImageClass OR 3-D NumPy array>: ImageClass object or NumPy array (3-D).

       - ifUseMask <Boolean> If set to true and mask is set on the ImageClass object then the image will show masked.

       - bandIndexesToUse <List of Ints> (optional) : List of Indexes of the bands to be shown.
       If empty then it will return all of them (default).

       - ifOnlyGetListOfPLTObjects <Boolean> (Optional): If set to True it won't plot the images (Mainly used in testing)

      Output :
       - Shows the images
       - Returns the list of the matplotlib.image.AxesImage objects (Mostly used in testing)

Usage - Show RGB

videometer.hips.showRGB(imageClass, ifUseMask=False):

   Function that shows srgb representation of the image.
   If ifUseForegroundMask is true then the image will be shown masked.

   Parameters
      Input :
       - image <ImageClass>: ImageClass object to be shown.
       - ifUseMask <Boolean>: To toggle mask on or off if set on the ImageClass object.

      Output :
       - Shows the images
       - Returns the matplotlib.image.AxesImage object (Mostly used for testing).

ImageClass

The center of the toolbox.

Attributes

• PixelValues - NumPy array of floats (3-D)
     Contains float pixel values of the HIPS image. Shape of the array is (height, width, bands).

• Height - Int
     Height of the HIPS image.

• Width - Int
     Width of the HIPS image.

• MmPixel - Float
     Physical size of each pixel in mm.

• Bands - Int
     Number of bands in the image.

• BandNames - NumPy array of strings
     List of names of the bands.

• WaveLengths - NumPy array of floats
     Contains wavelenghts of the bands in HIPS image.

• Description - String
     Description set of the image

• History - String
     Explains the history of the image.

• Illumination – NumPy array of strings
     List of Illumination name type of each band.

• StrobeTimes – NumPy array of int
     Strobe time in ms of each band in the image.

• StrobeTimesUniversal - NumPy array of floats
     Universal strobe time of each band in the image.

• FreehandLayers – List of dictionaries
     Each set Freehand layer is a dictionary with the following template :

{
    "name" : <string>
    "layerId" : <int>
    "description" : <string>
    "pixels" :  <2-D numpy array>
}    

• RGBPixels – NumPy array (height, width, 3)
     Array representing sRGB pixel values of the image.
     The values are set by using to_sRGB method in the ImageClass otherwise it will return None

• ForegroundPixels – NumPy array (2-D)
     Foreground mask of the image given as a binary 2-D numpy array.
     If Foreground pixels are not set on the image object it will return None.

• DeadPixels – NumPy array (2-D)
     Dead pixels of the image given as a binary 2-D numpy arra.
     If Dead pixels are not set on the image object it will return None.

• CorrectedPixels – NumPy array (2-D)
     Corrected pixels of the image given as a binary 2-D numpy array.
     If Corrected pixels are not set on the image object it will return None.

• SaturatedPixels – NumPy array (2-D)
     Saturated pixels of the image given as a binary 2-D numpy arra.
     If Saturated pixels are not set on the image object it will return None.

• ExtraData – Dictionary <string> : <Float>
     Contains additional information about the image (e.g. temperature data and similar).

• ExtraDataInt – Dictionary <string> : <Int>
     Contains additional information about the image.

• ExtraDataString – Dictionary <string> : <string>
     Contains additional information about the image.

Functions

• To_sRGB(spectraName="D65")
     Performs conversion of the spectral image to sRGB image.

   Parameters
      Input :
       - SpectraName (optional) <String> : Name of the spectra used for the transformation, default is D65.

      Output :
       - Returns the numpy sRGB image <NumPy array 2-D>
       - Updates the "RGBPixels" attribute

• extractBands(bandIndexesToUse)
     Similar to the Image Tools > Conversion > Extract bands in VideometerLab software.
     The bands and their information given in the bandsIndexesToUse remain in the ImageClass,
     others are deleted.

   Parameters
      Input :
       - bandIndexesToUse <List of Ints>: List of indexes of the bands to remain in the class.

      Output : None

Bugs or suggestions

Suggestions and bug reports may be sent to [e-mail]

Enjoy!

Licence

BSD-3-Clause-Clear license