Package cds.moc

Class Moc

java.lang.Object
cds.moc.Moc
All Implemented Interfaces:
Cloneable, Comparable<Moc>, Iterable<MocCell>
Direct Known Subclasses:
Moc1D, Moc2D

public abstract class Moc extends Object implements Iterable<MocCell>, Cloneable, Comparable<Moc>
Multi Order Coverage Map (MOC) This class provides read, write and process methods to manipulate a Multi Order Coverage Map (MOC). A MOC is used to define a Coverage in space, time, etc, or combination of these physical dimensions See: IVOA MOC 2.0 standard => https://www.ivoa.net/documents/MOC/ This abstract class Moc describes or implements the methods generic to MOCs, whatever their type (spatial, temporal, spatio-temporal, etc). This class is derived in 2 classes: Moc1D and Moc2D. Moc1D is a generic class for 1 physical dimensional MOCs, which is derived into SMOC (spatial MOCs) and TMoc (temporal MOCs). Moc2D is a generic class for 2-dimensional physical MOCs, which is derived into STMOC (space-time MOC) Warning: The cds.moc package has been completely revised/recoded when the IVOA MOC2.0 standard was published (2021). the HealpixMoc class is provided only to ensure compatibility with old software. It is only a wrapper to the new SMoc class that it is recommended to use instead. Note that some low level methods existing in HealpixMoc have not been reimplemented (cell lists by order) This package manipulates and stores MOCs only as a list of ranges (unlike its predecessor which used both a hierarchical and an range architecture). This refactoring was done to allow easy extension to MOCs covering other physical dimensions (currently only SPACE, TIME or TIME.SPACE) It uses code and algorithm initially developed by Jan Kotek, then refactored/extended by M.Reinecker, and re-extended for the specific needs of 2D MOCs (see Range and Range2 classes) Examples of uses are available in the class cds.moc.misc.MocExample and cds.moc.misc.MocTest The class cds.moc.misc.MocLint implements methods to validate the conformity of the binary or ASCII serialization of a MOC with the IVOA MOC 2.0 standard as well as its previous versions (1.1 and 1.0).
  • Field Details

  • Constructor Details

    • Moc

      public Moc()
      Main methods
  • Method Details

    • getMocOrderLogic

      public static int getMocOrderLogic()
      Get the current mocOrderLogic applied for operations (see setMocOrderLogic())
    • setMocOrderLogic

      public static void setMocOrderLogic(int logic)
      Set the current mocOrderLogic applied for operations: Default LOGIC_MAX LOGIC_MAX: MOC result for operations is returned with the Max orders of the 2 operandes => preserving area logic LOGIC_MIN: MOC result for operations is returned with the Min orders of the 2 operandes => preserving observation logic See IVOA 2.0 document
      Parameters:
      logic - LOGIC_MIN or LOGIC_MAX
    • createMoc

      public static Moc createMoc(String s) throws Exception
      Generic MOC factory. Recognize the MOC ASCII or JSON string and create the associated space, time or space-time MOC.
      Parameters:
      s - MOC string => ex: SMOC:3/1-4... TMOC:t29/3456-6788... STMOC:t27/... s29/...
      Returns:
      a MOC
      Throws:
      Exception
    • createMoc

      public static Moc createMoc(InputStream in) throws Exception
      Generic MOC factory. Recognize the MOC syntax (FITS, ASCII or JSON) and type (SMOC, TMOC or STMOC) and create the associated MOC.
      Parameters:
      in - the input stream
      Returns:
      a MOC
      Throws:
      Exception
    • setSpaceOrder

      public void setSpaceOrder(int order) throws Exception
      Generic getters/setters
      Throws:
      Exception
    • setTimeOrder

      public void setTimeOrder(int order) throws Exception
      Throws:
      Exception
    • getSpaceOrder

      public int getSpaceOrder()
    • getTimeOrder

      public int getTimeOrder()
    • setSpaceSys

      public void setSpaceSys(String sys)
    • getSpaceSys

      public String getSpaceSys()
    • setTimeSys

      public void setTimeSys(String sys)
    • getTimeSys

      public String getTimeSys()
    • getSpaceMoc

      public SMoc getSpaceMoc() throws Exception
      Throws:
      Exception
    • getTimeMoc

      public TMoc getTimeMoc() throws Exception
      Throws:
      Exception
    • getSpaceTimeMoc

      public STMoc getSpaceTimeMoc() throws Exception
      Throws:
      Exception
    • isSpace

      public boolean isSpace()
    • isTime

      public boolean isTime()
    • clone

      public abstract Moc clone() throws CloneNotSupportedException
      Clone Moc (deep copy)
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException
    • dup

      public abstract Moc dup()
      Create and instance of same class, same sys, but no data nor mocorder
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • toDebug

      public abstract String toDebug()
    • add

      public void add(String s) throws Exception
      Add a list of MOC elements provided in a string format (ASCII format or JSON format) ex basic ASCII: order1/npix1-npix2 npix3 ... order2/npix4 ... ex JSON: { "order1":[npix1,npix2,...], "order2":[npix3...] } Note : The string can be submitted in several times. In this case, the insertion will use the last current order Note : in JSON, the syntax is not checked ( in fact {, [ and " are ignored)
      Throws:
      Exception
    • json2ASCII

      protected String json2ASCII(String s)
    • clear

      public void clear()
      Clear the MOC - data only (not the properties, nor the mocOrder)
    • flush

      public abstract void flush()
      After adding process, required method before operating - not required for all classical API operations as it is already call
    • bufferSize

      public int bufferSize()
      Buffer size, not yet proceed
    • reduction

      public abstract boolean reduction(long maxSize) throws Exception
      Degrades the resolution(s) of the MOC until the RAM size of the MOC is reduced under the specified maximum (expressed in bytes).
      Throws:
      Exception
    • isEmpty

      public abstract boolean isEmpty()
      Return true if the Moc is empty (no coverage)
    • isFull

      public abstract boolean isFull()
      Return true if the Moc is full (full coverage)
    • getCoverage

      public abstract double getCoverage()
      Return the coverage pourcentage of the Moc
    • getMem

      public abstract long getMem()
      Return approximatively the amount of memory used for storing this MOC in RAM (in bytes)
    • getDeepestOrder

      public int getDeepestOrder()
      Return the hierarchical deepest required order - slow process, uses a cache
    • compareTo

      public int compareTo(Moc o)
      Comparator. Based on Moc coverage
      Specified by:
      compareTo in interface Comparable<Moc>
    • getNbRanges

      public abstract int getNbRanges()
      Return the number of ranges
    • setRangeList

      public abstract void setRangeList(Range range)
      Set the list of ranges - Warning: no copy
    • seeRangeList

      public abstract Range seeRangeList()
      Acces to the list of ranges (no copy)
    • iterator

      public Iterator<MocCell> iterator()
      Provide an Iterator on the MOC cell List (hierarchy view for Moc1D, and range highest order view for Moc2D)
      Specified by:
      iterator in interface Iterable<MocCell>
      Parameters:
      flagRange - true for getting range rather than all individual values
      Returns:
      mocCell => dim,order,startVal,endVal,Moc1D
    • cellIterator

      public abstract Iterator<MocCell> cellIterator(boolean flagRange)
    • clone1

      protected void clone1(Moc moc) throws CloneNotSupportedException
      Deep copy. The source is this, the target is the Moc in parameter
      Throws:
      CloneNotSupportedException
    • addToken

      protected abstract void addToken(String token) throws Exception
      Internal usage: Add one token element according to the format "[s|t]order/npix[-npixn]". If the order is not mentioned, use the last used order (currentOrder) Note: Also support JSON non standard IVOA syntax
      Parameters:
      token - one token (ex: s18/23-45)
      Throws:
      Exception
    • getMocOrder4op

      protected int getMocOrder4op(int m1, int m2)
      Return resulting order for operations. see setMocOrderLogic()
    • getNbCells

      public int getNbCells()
      Return the number of Moc cells (hierarchy Moc view) - slow process, uses a cache
    • resetCache

      protected void resetCache()
      Recalculates the metrics associated with the MOC hierarchical view: the number of hierarchical cells, the deepest order used...
    • computeHierarchy

      protected abstract void computeHierarchy()
      Recalculates the metrics associated with the MOC hierarchical view: the number of hierarchical cells, the deepest order used...
    • accretion

      public void accretion() throws Exception
      Prototypes
      Throws:
      Exception
    • setProperty

      public void setProperty(String key, String value) throws Exception
      MOC propertie setter
      Throws:
      Exception
    • setProperty

      public void setProperty(String key, String value, String comment) throws Exception
      Throws:
      Exception
    • getPropertyKeys

      public String[] getPropertyKeys()
      Provide the list of MOC property keys
    • getProperty

      public String getProperty(String key)
      Provide MOC property value.
    • getComment

      public String getComment(String key)
      Provide MOC property comment.
    • isCompatible

      public abstract boolean isCompatible(Moc moc)
      Operations
    • isIncluding

      public abstract boolean isIncluding(Moc moc) throws Exception
      Throws:
      Exception
    • isIntersecting

      public abstract boolean isIntersecting(Moc moc) throws Exception
      Throws:
      Exception
    • union

      public Moc union(Moc moc) throws Exception
      Return the Union with another Moc
      Throws:
      Exception
    • intersection

      public Moc intersection(Moc moc) throws Exception
      Return the Intersection with another Moc
      Throws:
      Exception
    • subtraction

      public Moc subtraction(Moc moc) throws Exception
      Return the subtraction with another Moc
      Throws:
      Exception
    • difference

      public Moc difference(Moc moc) throws Exception
      Return the difference with another Moc (not in A invalid input: '&' not in B)
      Throws:
      Exception
    • complement

      public abstract Moc complement() throws Exception
      Return the complement
      Throws:
      Exception
    • operation

      protected abstract Moc operation(Moc moc, int op) throws Exception
      Generic operations: 0-union, 1-intersection, 2-subtraction
      Throws:
      Exception
    • read

      public void read(String filename) throws Exception
      Read MOC from a file. Support standard FITS, ASCII and non standard JSON alternative
      Parameters:
      filename - file name
      Throws:
      Exception
    • read

      public void read(InputStream in) throws Exception
      Read MOC from a stream. Support standard FITS, ASCII and non standard JSON alternative
      Parameters:
      in - input stream (not closed at the end)
      Throws:
      Exception
    • read

      public void read(InputStream in, int mode) throws Exception
      Throws:
      Exception
    • readJSON

      public void readJSON(InputStream in) throws Exception
      Read MOC from an JSON stream
      Throws:
      Exception
    • readASCII

      public void readASCII(InputStream in) throws Exception
      Read MOC from an ASCII stream
      Throws:
      Exception
    • readFITS

      public void readFITS(InputStream in) throws Exception
      Read MOC from an Binary FITS stream
      Throws:
      Exception
    • readSpecificData

      protected abstract void readSpecificData(InputStream in, int naxis1, int naxis2, int nbyte, cds.moc.Moc.HeaderFits header) throws Exception
      Internal method: read FITS data according to the type of MOC.
      Parameters:
      in - The input stream
      naxis1 - size of FITS row (in bytes) (generally ==nbyte, but may be 1024 for buffering)
      naxis2 - number of values
      nbyte - size of each value (in bytes)
      header - HDU1 header
      Throws:
      Exception
    • readSpecificDataRange

      public abstract void readSpecificDataRange(int nval, byte[] t, int mode) throws Exception
      Throws:
      Exception
    • write

      public void write(String filename) throws Exception
      Write MOC in FITS binary serialization
      Throws:
      Exception
    • writeFITS

      public void writeFITS(String filename) throws Exception
      Write MOC in FITS binary serialization
      Throws:
      Exception
    • writeASCII

      public void writeASCII(String filename) throws Exception
      Write MOC in ASCII serialization
      Throws:
      Exception
    • writeJSON

      public void writeJSON(String filename) throws Exception
      Write MOC in JSON serialization (non IVOA standard)
      Throws:
      Exception
    • write

      public void write(String filename, int mode) throws Exception
      Write MOC to a file
      Parameters:
      filename - name of file
      mode - encoded format (FITS, ASCII or JSON)
      Throws:
      Exception
    • write

      public void write(OutputStream out, int mode) throws Exception
      Write MOC to a stream
      Parameters:
      mode - encoded format (FITS, ASCII or JSON)
      output - stream (not closed at the end)
      Throws:
      Exception
    • write

      public void write(OutputStream out) throws Exception
      Write MOC to an output stream in binary serialization
      Throws:
      Exception
    • writeASCII

      public abstract void writeASCII(OutputStream out) throws Exception
      Write MOC to an output stream in bASCII serialization
      Throws:
      Exception
    • writeJSON

      public abstract void writeJSON(OutputStream out) throws Exception
      Write MOC to an output stream in JSON serialization (non IVOA standard)
      Throws:
      Exception
    • writeFITS

      public void writeFITS(OutputStream out) throws Exception
      Write MOC to an output stream in binary FITS serialization
      Throws:
      Exception
    • getUnitDisk

      public static final String getUnitDisk(long val)
    • getUnitDisk

      public static final String getUnitDisk(long val, int unit, int format)
    • isCodedComp

      protected boolean isCodedComp(long a)
    • codeComp

      protected long codeComp(long a)
    • decodeComp

      protected long decodeComp(long a)
    • compressRange

      protected long[] compressRange(Range range, long unit)
      Compression of a range list based on coded singletons by storing only start index with 62e bit forced to 1
      Parameters:
      range - to be compressed
      unit - size of the range unit
      Returns:
      array of long with the exact required size after compression
    • uncompressRange

      protected Range uncompressRange(long[] r, long unit)
      Uncompression of an array of ranges based on coded singletons by storing only start index with 62e bit forced to 1
    • uncompressRange

      protected Range uncompressRange(long[] r, int sz, long unit)
    • toASCII

      public String toASCII() throws Exception
      Return Moc ASCII string
      Throws:
      Exception
    • toJSON

      public String toJSON() throws Exception
      Return Moc JSON string (non IVOA standard)
      Throws:
      Exception
    • writeASCII

      protected static int writeASCII(OutputStream out, Moc1D moc, boolean flagNL, boolean flagRange) throws Exception
      Internal method: Write ASCII Moc (1D) in an output stream
      Parameters:
      out - output stream
      moc - Moc to write
      flagNL - false for avoiding automatic NL
      flagRange - false for avoiding range expressions (ex: 32-35 => 32 33 34 35)
      Returns:
      the highest order found
      Throws:
      Exception
    • writeASCIIFlush

      protected static void writeASCIIFlush(OutputStream out, StringBuilder s, boolean nl) throws Exception
      Internal method: Flush the StringBuilder in the output stream. At the end, the StringBuilder is clear to be reused
      Parameters:
      out - The output Stream
      s - the stringBuilder to flush
      nl - true if a NL is inserted before
      Throws:
      Exception
    • sizeOfCoding

      public abstract int sizeOfCoding()
      Return the number of bytes used for coding each FITS value (4 for integer, 8 for long)
    • getNbCoding

      public abstract int getNbCoding()
      Return the number of values to write in FITS serialization
    • writeSpecificFitsProp

      protected abstract int writeSpecificFitsProp(OutputStream out) throws Exception
      Write specifical properties (depends of the Moc dimension:l SMOC, TMOC, STMOC...)
      Throws:
      Exception
    • writeData

      protected void writeData(OutputStream out) throws Exception
      Write data FITS section
      Throws:
      Exception
    • writeSpecificData

      protected int writeSpecificData(OutputStream out) throws Exception
      Write data (depends of the Moc dimension:l SMOC, TMOC, STMOC...)
      Throws:
      Exception
    • writeSpecificDataRange

      public abstract int writeSpecificDataRange(OutputStream out, int mode) throws Exception
      Write Moc data in Ranges
      Parameters:
      out - output stream
      mode - RAW or COMP_SINGLETON
      Returns:
      number of bytes written
      Throws:
      Exception
    • writeVal

      protected static int writeVal(OutputStream out, long val, byte[] buf) throws Exception
      Write a val (int or long) in the outputstream out, using the buffer buf. The size of the buf determines int or long
      Parameters:
      out - output stream
      val - value to write
      buf - buffer to use
      Returns:
      the number of bytes written
      Throws:
      Exception
    • readLong

      protected static long readLong(byte[] t, int i)
      Convert 8 consecutive bytes as long (starting at the index i)
      Parameters:
      t - array
      i - offset
      Returns:
      long decoded
    • hpix2uniq

      public static long hpix2uniq(int order, long npix)
      Code a couple (order,npix) into a unique long integer
      Parameters:
      order - HEALPix order
      npix - HEALPix number
      Returns:
      Uniq long ordering
    • uniq2hpix

      public static long[] uniq2hpix(long uniq)
      Uncode a long integer into a couple (order,npix)
      Parameters:
      uniq - Uniq long ordering
      Returns:
      HEALPix order,number
    • uniq2hpix

      public static long[] uniq2hpix(long uniq, long[] hpix)
      Uncode a long integer into a couple (order,npix)
      Parameters:
      uniq - Uniq long ordering
      hpix - null for reallocating target couple
      Returns:
      HEALPix order,number
    • pow2

      public static final long pow2(long order)
    • log2

      public static final long log2(long nside)
    • getFitsLine

      protected static byte[] getFitsLine(String key, String value, String comment)
      Generate FITS 80 character line.
      Parameters:
      key - The FITS key
      value - The associated FITS value (can be numeric, string (quoted or not)
      comment - The commend, or null
      Returns:
      the 80 character FITS line
    • getFitsLine

      protected static byte[] getFitsLine(String key, String value, String comment, boolean forceStringMode)
    • getBourrage

      protected static byte[] getBourrage(int currentPos)
      Generate the end of a FITS block assuming a current block size of headSize bytes
    • readFully

      public static void readFully(InputStream in, byte[] buf) throws IOException
      Fully read buf.length bytes from in input stream
      Throws:
      IOException
    • readFully

      public static void readFully(InputStream in, byte[] buf, int offset, int len) throws IOException
      Fully read len bytes from in input stream and store the result in buf[] from offset position.
      Throws:
      IOException