Interface ArrayAccess

  • All Superinterfaces:
    ArrayDescription
    All Known Implementing Classes:
    DefaultArrayAccess

    public interface ArrayAccess
    extends ArrayDescription
    Provides methods to read and write pixels from an NDArray. The actual read and write methods deal with reading from the NDArray pixel data into a java primitive array or writing from a java primitive array into NDArray pixel data. While this can be used to do single pixel read/writes, it is more efficient to read/write a moderate-sized bufferfull at once. The ChunkStepper class is provided as a convenience to assist with this sort of processing.

    The accessor maintains an offset position which determines the starting position of the next read/write. This may be modified by the setOffset or setPosition methods. The mapping between offset values and position vectors is determined by the pixel ordering scheme of this ArrayAccess (as determined by its OrderedNDShape).

    Not all methods will work on a given accessor, depending on what it is capable of; if the isRandom method returns false then the offset may not be set to a position before its current position; if isReadable returns false then the read and readTile methods will fail; and if isWritable returns false then the write and writeTile methods will fail. In each of these cases the illegal accesses will result in an UnsupportedOperationException.

    If the read or write methods result in an IOException this will have the side effect of closing this accessor for further access (since under these circumstances the current offset may not be known).

    Author:
    Mark Taylor (Starlink)
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Shuts down this accessor for further data access.
      java.lang.Object getMapped()
      Returns a single primitive array holding all the data of this array.
      long getOffset()
      Returns the current offset into the array for read/write.
      long[] getPosition()
      Returns the coordinates at which the next read/write will occur.
      boolean isMapped()
      Indicates whether mapped access is available.
      void read​(java.lang.Object buffer, int start, int size)
      Reads a number of pixels from the current offset into a specified part of a supplied primitive array.
      void readTile​(java.lang.Object buffer, NDShape tileShape)
      Reads a tile of pixels into a supplied primitive array.
      void setOffset​(long off)
      Sets the offset into the array for the next read/write to occur.
      void setPosition​(long[] pos)
      Sets the coordinates for the next read/write to occur.
      void write​(java.lang.Object buffer, int start, int size)
      Writes a number of pixels starting at the current offset from a specified part of a supplied primitive array.
      void writeTile​(java.lang.Object buffer, NDShape tileShape)
      Writes a tile of pixels from a supplied primitive array.
    • Method Detail

      • getOffset

        long getOffset()
        Returns the current offset into the array for read/write.
        Returns:
        the index of the next element to be read/written
      • setOffset

        void setOffset​(long off)
                throws java.io.IOException
        Sets the offset into the array for the next read/write to occur. Attempting to set the offset to a lower value than its current one will fail if random access is not available (isRandom is false).
        Parameters:
        off - the position at which the next read/write will start
        Throws:
        java.io.IOException - if some unexpected I/O error occurs
        java.lang.IndexOutOfBoundsException - if off<0 or off>=npixel
        java.lang.IllegalStateException - if this accessor has been closed
        java.lang.UnsupportedOperationException - if an attempt is made to set the offset to a value lower than its current one, and random access is not available for this accessor
      • getPosition

        long[] getPosition()
        Returns the coordinates at which the next read/write will occur.
        Returns:
        an N-element array giving the coordinates of the next read/write
      • setPosition

        void setPosition​(long[] pos)
                  throws java.io.IOException
        Sets the coordinates for the next read/write to occur. Attempting to set the coordinates so that the new offset corresponds to a lower value than its current one will fail if random access is not available (isRandom returns false).
        Parameters:
        pos - an N-element array giving the coordinates for the next read/write
        Throws:
        java.io.IOException - if some unexpected I/O error occurs
        java.lang.IndexOutOfBoundsException - if pos is outside the array
        java.lang.IllegalStateException - if this accessor has been closed
        java.lang.UnsupportedOperationException - if an attempt is made to set the offset to a value lower than its current one, and random access is not available
      • read

        void read​(java.lang.Object buffer,
                  int start,
                  int size)
           throws java.io.IOException
        Reads a number of pixels from the current offset into a specified part of a supplied primitive array. The current offset will be updated accordingly (to the point after the read pixels).

        An IOException during the read will have the effect of closing this accessor for further access.

        Parameters:
        buffer - an array of the appropriate primitive type for this accessor into whose elements start..start+size the next size pixels will be read
        start - the starting offset into buffer into which the pixels should be read
        size - the number of pixels to read (also the amount by which the current offset will be incremented)
        Throws:
        java.io.IOException - if there is an I/O error
        java.lang.UnsupportedOperationException - if this accessor is not readable (isReadable returns false)
        java.lang.IllegalStateException - if this accessor has been closed
        java.lang.IllegalArgumentException - if buffer is not an array of primitives with type matching the type of this accessor, or if it has less than start+size elements
      • readTile

        void readTile​(java.lang.Object buffer,
                      NDShape tileShape)
               throws java.io.IOException
        Reads a tile of pixels into a supplied primitive array. A tile is an N-dimensional hypercuboid specified by an NDShape object. The pixels are read into a given array in the order implied by the ordering scheme of this object. The specified tile must have the same dimensionality as this accessor, but need not lie wholly or partially within its bounds -- pixels outside the intersection will be given the bad value.

        The current offset will be updated to the point after the last pixel in the intersection between the tile and this accessor.

        It is possible to read a tile when random access is not available, but only if the first pixel in the requested tile is ahead of the current offset.

        An IOException during the read will have the effect of closing this accessor for further access.

        Parameters:
        buffer - an array of the appropriate primitive type for this accessor and at least as long as the number of pixels in tileShape
        tileShape - an NDShape object specifying the shape of the tile to be read
        Throws:
        java.io.IOException - if there is an I/O error
        java.lang.UnsupportedOperationException - if this object is not readable (isReadable returns false) or if it would be necessary to read a part of the data earlier than the current offset and random access is not available
        java.lang.IllegalArgumentException - if buffer is not an array of the right primitive type or has too few elements
        java.lang.IllegalStateException - if this accessor has been closed
      • write

        void write​(java.lang.Object buffer,
                   int start,
                   int size)
            throws java.io.IOException
        Writes a number of pixels starting at the current offset from a specified part of a supplied primitive array. The current offset will be updated accordingly (to the point after the last write).

        If an IOException occurs during the read, this will have the additional effect of closing this accessor for further access.

        Parameters:
        buffer - an array of the appropriate primitive type for this NDArray whose elements start..start+size will be written out
        start - the starting point in buffer from which pixels will be written
        size - the number of pixels to write (also the amount by which the current offset will be incremented)
        Throws:
        java.io.IOException - if there is an I/O error
        java.lang.UnsupportedOperationException - if this accessor is not writable (isWritable returns false)
        java.lang.IllegalStateException - if this accessor has been closed
        java.lang.IllegalArgumentException - if buffer is not an array of primitives with type matching the type of this accessor, or if it has less than start+size elements
      • writeTile

        void writeTile​(java.lang.Object buffer,
                       NDShape tileShape)
                throws java.io.IOException
        Writes a tile of pixels from a supplied primitive array. A tile is an N-dimensional hypercuboid specified by an NDShape object. The ordering of pixels in the array is implied by the ordering scheme of this object. The specified tile must have the same dimensionality as this accessor, but need not lie wholly or partially within its bounds -- pixels outside the intersection will simply be ignored.

        The current offset will be updated to the point after the last pixel in the intersection between the tile and this accessor.

        It is possible to read a tile when random access is not available, but only if the first pixel in the requested tile is ahead of the current offset.

        If an IOException occurs during the write, this will have the additional effect of closing this accessor for further access.

        Parameters:
        buffer - an array of the appropriate primitive type for this NDArray and at least as long as the number of pixels in tileShape (elements after this limit will be ignored)
        tileShape - an NDShape object specifying the shape of the tile to be written
        Throws:
        java.io.IOException - if there is an I/O error
        java.lang.UnsupportedOperationException - if this accessor is not writable (isWritable returns false) or if it would be necessary to write a part of the data earlier than the current offset and random access is not available
        java.lang.IllegalArgumentException - if buffer is not an array of the right primitive type or has too few elements
        java.lang.IllegalStateException - if this accessor has been closed
      • isMapped

        boolean isMapped()
        Indicates whether mapped access is available. If true, the getMapped method will return a reference to the java primitive array containing all the pixels of this NDArray. The return value must not change over the lifetime of this object.
        Returns:
        true if mapped access is possible
      • getMapped

        java.lang.Object getMapped()
        Returns a single primitive array holding all the data of this array. Calling this method does not do significant work, but returns a reference to an existing mapped array. Access to the array data using this method, if available, will be more efficient than by using the read/write methods. In the case of a writable accessor, making changes to the returned primitive array will result in changes to the accessor pixel data. In the case of an accessor which is not writable, the effect of making changes to the returned array is undefined; in particular it may result in an exception.

        The method will fail unless isMapped returns true.

        Returns:
        a primitive array, of type implied by the Type of this object, containing all the pixels of this array, in its natural ordering
        Throws:
        java.lang.UnsupportedOperationException - if mapped access is not available
        java.lang.IllegalStateException - if this accessor has been closed
      • close

        void close()
            throws java.io.IOException
        Shuts down this accessor for further data access. Following a call to close the offset will have an illegal value and calls to any read, write or position setting methods will fail with an IllegalStateException. A close should always be called on an ArrayAccess when it is finished with. In the case of a readable object it enables release of associated resources beyond those taken care of by the garbage collector, and in the case of writable object it may also be required to ensure that data is actually flushed to the underlying data storage. This method may harmlessly be called on an accessor which has already been closed.
        Throws:
        java.io.IOException - if there is an I/O error