Class NTv2.Loader
- Enclosing class:
NTv2
A NTv2 file contains an arbitrary number of sub-files, where each sub-file is a grid. There is at least one grid (the parent), and potentially many sub-grids of higher density. At the beginning is an overview header block of information that is common to all sub-files. Then there is other headers specific to each sub-files.
While this loader is primarily targeted at loading NTv2 files, it can also opportunistically read NTv1 files. The two file formats differ by some header records having different names (but same meanings), the possibility to have sub-grids and the presence of accuracy information.
- Since:
- 0.7
- Version:
- 1.1
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static enum
Type of data allowed in header records. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate String
Dates at which the grid has been created or updated, ornull
if unknown.private boolean
true
if theheader
map contains at least one key associated to a null value.The headers content, as the union of the overview header and the header in process of being read.private final boolean
true
if we are reading a NTv2 file, orfalse
if we are reading a NTv1 file.private static final int
Maximum number of characters for a key in a header record.private final int
Number of grids expected in the file.private final String[]
Keys ofheader
for entries that were declared in the overview header.private static final int
Size of a record.private static final Map
<String, NTv2.Loader.DataType> Some known keywords that may appear in NTv2 header records, associated the the expected type of values.private String
Dates at which the grid has been created or updated, ornull
if unknown.Fields inherited from class org.apache.sis.internal.referencing.provider.DatumShiftGridLoader
buffer, DEGREES_TO_SECONDS, file, SECOND_PRECISION
-
Constructor Summary
ConstructorsConstructorDescriptionLoader
(ReadableByteChannel channel, Path file, int version) Creates a new reader for the given channel. -
Method Summary
Modifier and TypeMethodDescriptionprivate Object
Gets the value for the given key.private Object
Returns the value for the given key, or thrown an exception if the value is not found.private static boolean
isLittleEndian
(int n) Returnstrue
if the given value seems to be stored in little endian order.(package private) final DatumShiftGridFile
<javax.measure.quantity.Angle, javax.measure.quantity.Angle> Reads all grids and returns the root grid.private void
readGrid
(Map<String, DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>> addTo, Map<String, List<DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>>> children) Reads the next grid, starting at the current position.private void
readHeader
(int numRecords, String numkey) Reads all records found in the header, starting from the current buffer position.private String
readString
(int length) Reads a string at the current buffer position, assuming ASCII encoding.(package private) void
report
(Class<? extends AbstractProvider> caller) If we had any warnings during the loading process, report them now.Methods inherited from class org.apache.sis.internal.referencing.provider.DatumShiftGridLoader
canNotLoad, ensureBufferContains, log, skip, startLoading
-
Field Details
-
RECORD_LENGTH
private static final int RECORD_LENGTHSize of a record. This value applies to both the header records and the data records. In the case of header records, this is the size of the key plus the size of the value.- See Also:
-
KEY_LENGTH
private static final int KEY_LENGTHMaximum number of characters for a key in a header record. Expected keys are listed in theTYPES
map.- See Also:
-
TYPES
Some known keywords that may appear in NTv2 header records, associated the the expected type of values. The type is not encoded in a NTv2 file; it has to be hard-coded in this table. The first 11 entries in this map (ignoring entries marked by "NTv1") are typically found in overview header, and the remaining entries in the sub-grid headers. -
header
The headers content, as the union of the overview header and the header in process of being read. Keys are strings like"VERSION"
,"SYSTEM_F"
,"LONG_INC"
, etc.. Values areString
,Integer
orDouble
. If some keys are unrecognized, they will be put in this map with thenull
value and thehasUnrecognized
flag will be set totrue
. -
overviewKeys
Keys ofheader
for entries that were declared in the overview header. This is used afterreadGrid(Map, Map)
execution for discarding all entries specific to sub-grids, for avoiding to mix entries from two sub-grids. -
isV2
private final boolean isV2true
if we are reading a NTv2 file, orfalse
if we are reading a NTv1 file. -
hasUnrecognized
private boolean hasUnrecognizedtrue
if theheader
map contains at least one key associated to a null value. -
numGrids
private final int numGridsNumber of grids expected in the file. -
created
Dates at which the grid has been created or updated, ornull
if unknown. Used for information purpose only. -
updated
Dates at which the grid has been created or updated, ornull
if unknown. Used for information purpose only.
-
-
Constructor Details
-
Loader
Loader(ReadableByteChannel channel, Path file, int version) throws IOException, org.opengis.util.FactoryException Creates a new reader for the given channel. This constructor parses the header immediately, but does not read any grid. A hint about expected NTv2 version is given, but this constructor may override that hint with information found in the file.- Parameters:
channel
- where to read data from.file
- path to the longitude and latitude difference file. Used for parameter declaration and error reporting.version
- the expected version (1 or 2).- Throws:
org.opengis.util.FactoryException
- if a data record cannot be parsed.IOException
-
-
Method Details
-
isLittleEndian
private static boolean isLittleEndian(int n) Returnstrue
if the given value seems to be stored in little endian order. The strategy is to read an integer that we expect to be small (the HEADER or NUM_OREC value which should be 12 or 11) and to check which order gives the smallest value. -
readString
Reads a string at the current buffer position, assuming ASCII encoding. After this method call, the buffer position will be the first byte after the string. The buffer content is unmodified.- Parameters:
length
- number of bytes to read.
-
readHeader
private void readHeader(int numRecords, String numkey) throws IOException, org.opengis.util.FactoryException Reads all records found in the header, starting from the current buffer position. The header may be the overview header (in which case we expect a number of records given byHEADER
orNUM_OREC
value) or a sub-grid header (in which case we expectNUM_SREC
records).The
numRecords
given in argument is a default value. It will be updated as soon as thenumKey
record is found.- Parameters:
numRecords
- default number of expected records (usually 11).numkey
- key of the record giving the number of records:"NUM_OREC"
or"NUM_SREC"
.- Throws:
IOException
org.opengis.util.FactoryException
-
readAllGrids
final DatumShiftGridFile<javax.measure.quantity.Angle,javax.measure.quantity.Angle> readAllGrids() throws IOException, org.opengis.util.FactoryException, org.opengis.referencing.operation.NoninvertibleTransformExceptionReads all grids and returns the root grid. After reading all grids, this method rearrange them in a child-parent relationship. The result is a tree with a single root containing sub-grids (if any) as children.- Throws:
IOException
org.opengis.util.FactoryException
org.opengis.referencing.operation.NoninvertibleTransformException
-
readGrid
private void readGrid(Map<String, DatumShiftGridFile<javax.measure.quantity.Angle, throws IOException, org.opengis.util.FactoryException, org.opengis.referencing.operation.NoninvertibleTransformExceptionjavax.measure.quantity.Angle>> addTo, Map<String, List<DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle>>> children) Reads the next grid, starting at the current position. A NTv2 file can have many grids. This can be used for grids having different resolutions depending on the geographic area. The first grid can cover a large area with a coarse resolution, and next grids cover smaller areas overlapping the first grid but with finer resolution.NTv2 grids contain also information about shifts accuracy. This is not yet handled by SIS, except for determining an approximate grid cell resolution.
- Parameters:
addTo
- the map where to add the grid with the grid name as the key.children
- the map where to add children with the parent name as the key.- Throws:
IOException
org.opengis.util.FactoryException
org.opengis.referencing.operation.NoninvertibleTransformException
-
get
Gets the value for the given key. If the value is absent, then this method throws an exception ifmandatory
istrue
or returnsnull
otherwise.- Parameters:
key
- key of the value to search.mandatory
- whether to throw an exception if the value is not found.- Returns:
- value associated to the given key, or
null
if none and not mandatory. - Throws:
org.opengis.util.FactoryException
-
get
Returns the value for the given key, or thrown an exception if the value is not found. Before to fail if the key is not found, this method searches for a value associated to an alternative name. That alternative should be the name used in legacy NTv1.- Parameters:
key
- key of the value to search.alt
- alternative key name, or name used in NTv1, ornull
if none.kv1
- name used in NTv1, ornull
if none.- Returns:
- value associated to the given key (never
null
). - Throws:
org.opengis.util.FactoryException
-
report
If we had any warnings during the loading process, report them now.- Parameters:
caller
- the provider which created this loader.
-