Package cds.moc
Class Moc
java.lang.Object
cds.moc.Moc
- All Implemented Interfaces:
Cloneable
,Comparable<Moc>
,Iterable<MocCell>
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final int
protected int
protected int
protected int
static final int
protected static String
Utilsstatic final int
static final int
static final int
static final int
Factories & global parametersstatic long
protected static final int
protected static final int
ASCII writersprotected LinkedHashMap<String,
String> MOC Properties and commentsstatic final int
Two binary serialization - RAW is the IVOA standardstatic final String[]
static long
static final String
MOC API version number -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Prototypesvoid
Add a list of MOC elements provided in a string format (ASCII format or JSON format) ex basic ASCII: order1/npix1-npix2 npix3 ...protected abstract void
Internal usage: Add one token element according to the format "[s|t]order/npix[-npixn]".int
Buffer size, not yet proceedcellIterator
(boolean flagRange) void
clear()
Clear the MOC - data only (not the properties, nor the mocOrder)abstract Moc
clone()
Clone Moc (deep copy)protected void
Deep copy.protected long
codeComp
(long a) int
Comparator.abstract Moc
Return the complementprotected 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 1protected abstract void
Recalculates the metrics associated with the MOC hierarchical view: the number of hierarchical cells, the deepest order used...static Moc
createMoc
(InputStream in) Generic MOC factory.static Moc
Generic MOC factory.protected long
decodeComp
(long a) difference
(Moc moc) Return the difference with another Moc (not in A & not in B)abstract Moc
dup()
Create and instance of same class, same sys, but no data nor mocorderabstract void
flush()
After adding process, required method before operating - not required for all classical API operations as it is already callprotected static byte[]
getBourrage
(int currentPos) Generate the end of a FITS block assuming a current block size of headSize bytesgetComment
(String key) Provide MOC property comment.abstract double
Return the coverage pourcentage of the Mocint
Return the hierarchical deepest required order - slow process, uses a cacheprotected static byte[]
getFitsLine
(String key, String value, String comment) Generate FITS 80 character line.protected static byte[]
getFitsLine
(String key, String value, String comment, boolean forceStringMode) abstract long
getMem()
Return approximatively the amount of memory used for storing this MOC in RAM (in bytes)protected int
getMocOrder4op
(int m1, int m2) Return resulting order for operations.static int
Get the current mocOrderLogic applied for operations (see setMocOrderLogic())int
Return the number of Moc cells (hierarchy Moc view) - slow process, uses a cacheabstract int
Return the number of values to write in FITS serializationabstract int
Return the number of rangesgetProperty
(String key) Provide MOC property value.String[]
Provide the list of MOC property keysint
int
static final String
getUnitDisk
(long val) static final String
getUnitDisk
(long val, int unit, int format) static long
hpix2uniq
(int order, long npix) Code a couple (order,npix) into a unique long integerintersection
(Moc moc) Return the Intersection with another Mocprotected boolean
isCodedComp
(long a) abstract boolean
isCompatible
(Moc moc) Operationsabstract boolean
isEmpty()
Return true if the Moc is empty (no coverage)abstract boolean
isFull()
Return true if the Moc is full (full coverage)abstract boolean
isIncluding
(Moc moc) abstract boolean
isIntersecting
(Moc moc) boolean
isSpace()
boolean
isTime()
iterator()
Provide an Iterator on the MOC cell List (hierarchy view for Moc1D, and range highest order view for Moc2D)protected String
json2ASCII
(String s) static final long
log2
(long nside) protected abstract Moc
Generic operations: 0-union, 1-intersection, 2-subtractionstatic final long
pow2
(long order) void
read
(InputStream in) Read MOC from a stream.void
read
(InputStream in, int mode) void
Read MOC from a file.void
readASCII
(InputStream in) Read MOC from an ASCII streamvoid
readFITS
(InputStream in) Read MOC from an Binary FITS streamstatic void
readFully
(InputStream in, byte[] buf) Fully read buf.length bytes from in input streamstatic void
readFully
(InputStream in, byte[] buf, int offset, int len) Fully read len bytes from in input stream and store the result in buf[] from offset position.void
readJSON
(InputStream in) Read MOC from an JSON streamprotected static long
readLong
(byte[] t, int i) Convert 8 consecutive bytes as long (starting at the index i)protected abstract void
readSpecificData
(InputStream in, int naxis1, int naxis2, int nbyte, cds.moc.Moc.HeaderFits header) Internal method: read FITS data according to the type of MOC.abstract void
readSpecificDataRange
(int nval, byte[] t, int mode) abstract boolean
reduction
(long maxSize) Degrades the resolution(s) of the MOC until the RAM size of the MOC is reduced under the specified maximum (expressed in bytes).protected void
Recalculates the metrics associated with the MOC hierarchical view: the number of hierarchical cells, the deepest order used...abstract Range
Acces to the list of ranges (no copy)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 documentvoid
setProperty
(String key, String value) MOC propertie settervoid
setProperty
(String key, String value, String comment) abstract void
setRangeList
(Range range) Set the list of ranges - Warning: no copyvoid
setSpaceOrder
(int order) Generic getters/settersvoid
setSpaceSys
(String sys) void
setTimeOrder
(int order) void
setTimeSys
(String sys) abstract int
Return the number of bytes used for coding each FITS value (4 for integer, 8 for long)subtraction
(Moc moc) Return the subtraction with another MoctoASCII()
Return Moc ASCII stringabstract String
toDebug()
toJSON()
Return Moc JSON string (non IVOA standard)toString()
protected Range
uncompressRange
(long[] r, int sz, long unit) 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 1Return the Union with another Mocstatic long[]
uniq2hpix
(long uniq) Uncode a long integer into a couple (order,npix)static long[]
uniq2hpix
(long uniq, long[] hpix) Uncode a long integer into a couple (order,npix)void
write
(OutputStream out) Write MOC to an output stream in binary serializationvoid
write
(OutputStream out, int mode) Write MOC to a streamvoid
Write MOC in FITS binary serializationvoid
Write MOC to a fileabstract void
writeASCII
(OutputStream out) Write MOC to an output stream in bASCII serializationprotected static int
writeASCII
(OutputStream out, Moc1D moc, boolean flagNL, boolean flagRange) Internal method: Write ASCII Moc (1D) in an output streamvoid
writeASCII
(String filename) Write MOC in ASCII serializationprotected static void
writeASCIIFlush
(OutputStream out, StringBuilder s, boolean nl) Internal method: Flush the StringBuilder in the output stream.protected void
writeData
(OutputStream out) Write data FITS sectionvoid
writeFITS
(OutputStream out) Write MOC to an output stream in binary FITS serializationvoid
Write MOC in FITS binary serializationabstract void
writeJSON
(OutputStream out) Write MOC to an output stream in JSON serialization (non IVOA standard)void
Write MOC in JSON serialization (non IVOA standard)protected int
Write data (depends of the Moc dimension:l SMOC, TMOC, STMOC...)abstract int
writeSpecificDataRange
(OutputStream out, int mode) Write Moc data in Rangesprotected abstract int
Write specifical properties (depends of the Moc dimension:l SMOC, TMOC, STMOC...)protected static int
writeVal
(OutputStream out, long val, byte[] buf) Write a val (int or long) in the outputstream out, using the buffer buf.Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Field Details
-
VERSION
MOC API version number- See Also:
-
RAW
public static final int RAWTwo binary serialization - RAW is the IVOA standard- See Also:
-
COMPRESS_SINGLETON
public static final int COMPRESS_SINGLETON- See Also:
-
FITS
public static final int FITS- See Also:
-
ASCII
public static final int ASCII- See Also:
-
JSON
public static final int JSON- See Also:
-
cacheNbCells
protected int cacheNbCells -
cacheDeepestOrder
protected int cacheDeepestOrder -
cacheHashCode
protected int cacheHashCode -
property
MOC Properties and comments -
comment
-
LOGIC_MIN
public static final int LOGIC_MINFactories & global parameters- See Also:
-
LOGIC_MAX
public static final int LOGIC_MAX- See Also:
-
CR
Utils -
unites
-
MASK_COMP
public static long MASK_COMP -
UNMASK_COMP
public static long UNMASK_COMP -
MAXWORD
protected static final int MAXWORDASCII writers- See Also:
-
MAXSIZE
protected static final int MAXSIZE- See Also:
-
-
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
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
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
Generic getters/setters- Throws:
Exception
-
setTimeOrder
- Throws:
Exception
-
getSpaceOrder
public int getSpaceOrder() -
getTimeOrder
public int getTimeOrder() -
setSpaceSys
-
getSpaceSys
-
setTimeSys
-
getTimeSys
-
getSpaceMoc
- Throws:
Exception
-
getTimeMoc
- Throws:
Exception
-
getSpaceTimeMoc
- Throws:
Exception
-
isSpace
public boolean isSpace() -
isTime
public boolean isTime() -
clone
Clone Moc (deep copy)- Overrides:
clone
in classObject
- Throws:
CloneNotSupportedException
-
dup
Create and instance of same class, same sys, but no data nor mocorder -
toString
-
toDebug
-
add
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
-
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
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
Comparator. Based on Moc coverage- Specified by:
compareTo
in interfaceComparable<Moc>
-
getNbRanges
public abstract int getNbRanges()Return the number of ranges -
setRangeList
Set the list of ranges - Warning: no copy -
seeRangeList
Acces to the list of ranges (no copy) -
iterator
Provide an Iterator on the MOC cell List (hierarchy view for Moc1D, and range highest order view for Moc2D) -
cellIterator
-
clone1
Deep copy. The source is this, the target is the Moc in parameter- Throws:
CloneNotSupportedException
-
addToken
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
Prototypes- Throws:
Exception
-
setProperty
MOC propertie setter- Throws:
Exception
-
setProperty
- Throws:
Exception
-
getPropertyKeys
Provide the list of MOC property keys -
getProperty
Provide MOC property value. -
getComment
Provide MOC property comment. -
isCompatible
Operations -
isIncluding
- Throws:
Exception
-
isIntersecting
- Throws:
Exception
-
union
Return the Union with another Moc- Throws:
Exception
-
intersection
Return the Intersection with another Moc- Throws:
Exception
-
subtraction
Return the subtraction with another Moc- Throws:
Exception
-
difference
Return the difference with another Moc (not in A & not in B)- Throws:
Exception
-
complement
Return the complement- Throws:
Exception
-
operation
Generic operations: 0-union, 1-intersection, 2-subtraction- Throws:
Exception
-
read
Read MOC from a file. Support standard FITS, ASCII and non standard JSON alternative- Parameters:
filename
- file name- Throws:
Exception
-
read
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
- Throws:
Exception
-
readJSON
Read MOC from an JSON stream- Throws:
Exception
-
readASCII
Read MOC from an ASCII stream- Throws:
Exception
-
readFITS
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 streamnaxis1
- size of FITS row (in bytes) (generally ==nbyte, but may be 1024 for buffering)naxis2
- number of valuesnbyte
- size of each value (in bytes)header
- HDU1 header- Throws:
Exception
-
readSpecificDataRange
- Throws:
Exception
-
write
Write MOC in FITS binary serialization- Throws:
Exception
-
writeFITS
Write MOC in FITS binary serialization- Throws:
Exception
-
writeASCII
Write MOC in ASCII serialization- Throws:
Exception
-
writeJSON
Write MOC in JSON serialization (non IVOA standard)- Throws:
Exception
-
write
Write MOC to a file- Parameters:
filename
- name of filemode
- encoded format (FITS, ASCII or JSON)- Throws:
Exception
-
write
Write MOC to a stream- Parameters:
output
- stream (not closed at the end)mode
- encoded format (FITS, ASCII or JSON)- Throws:
Exception
-
write
Write MOC to an output stream in binary serialization- Throws:
Exception
-
writeASCII
Write MOC to an output stream in bASCII serialization- Throws:
Exception
-
writeJSON
Write MOC to an output stream in JSON serialization (non IVOA standard)- Throws:
Exception
-
writeFITS
Write MOC to an output stream in binary FITS serialization- Throws:
Exception
-
getUnitDisk
-
getUnitDisk
-
isCodedComp
protected boolean isCodedComp(long a) -
codeComp
protected long codeComp(long a) -
decodeComp
protected long decodeComp(long a) -
compressRange
Compression of a range list based on coded singletons by storing only start index with 62e bit forced to 1- Parameters:
range
- to be compressedunit
- size of the range unit- Returns:
- array of long with the exact required size after compression
-
uncompressRange
Uncompression of an array of ranges based on coded singletons by storing only start index with 62e bit forced to 1 -
uncompressRange
-
toASCII
Return Moc ASCII string- Throws:
Exception
-
toJSON
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 streammoc
- Moc to writeflagNL
- false for avoiding automatic NLflagRange
- 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 Streams
- the stringBuilder to flushnl
- 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
Write specifical properties (depends of the Moc dimension:l SMOC, TMOC, STMOC...)- Throws:
Exception
-
writeData
Write data FITS section- Throws:
Exception
-
writeSpecificData
Write data (depends of the Moc dimension:l SMOC, TMOC, STMOC...)- Throws:
Exception
-
writeSpecificDataRange
Write Moc data in Ranges- Parameters:
out
- output streammode
- RAW or COMP_SINGLETON- Returns:
- number of bytes written
- Throws:
Exception
-
writeVal
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 streamval
- value to writebuf
- 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
- arrayi
- 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 ordernpix
- 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 orderinghpix
- 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
Generate FITS 80 character line.- Parameters:
key
- The FITS keyvalue
- The associated FITS value (can be numeric, string (quoted or not)comment
- The commend, or null- Returns:
- the 80 character FITS line
-
getFitsLine
-
getBourrage
protected static byte[] getBourrage(int currentPos) Generate the end of a FITS block assuming a current block size of headSize bytes -
readFully
Fully read buf.length bytes from in input stream- Throws:
IOException
-
readFully
Fully read len bytes from in input stream and store the result in buf[] from offset position.- Throws:
IOException
-