Package com.luciad.format.magneticnorth

Class TLcdWMMMagneticNorthMap

java.lang.Object
com.luciad.format.magneticnorth.TLcdWMMMagneticNorthMap
All Implemented Interfaces:
ILcdMagneticNorthMap, ILcdInputStreamFactoryCapable
public class TLcdWMMMagneticNorthMap extends Object implements ILcdInputStreamFactoryCapable
This class is a mapping between the declination, inclination or the total intensity of the magnetic north at a given point and date.

Be sure to use the same TLcdWMMMagneticNorthMap for successive calculations since it performs caching.

The model used for the calculations has a limited life span. If you try to perform calculations outside this lifespan, an exception will be thrown. You can set this class to ignore the limited lifespan with the method setIgnoreModelLifeSpan. In this case, no exception will be thrown when you perform calculations outside the lifespan.

Multiple data file names, for multiple life spans can be used for this map. The map will always switch to the correct data file when setDate(java.util.Calendar) is called. Note that the user of this class is responsible for setting the data file names.

Check out http://www.ngdc.noaa.gov/geomag/geomag.shtml for more info about the used terms.
Check out http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml for more information about the used model.

This implementation is not thread-safe

  • Field Details

  • Constructor Details

    • TLcdWMMMagneticNorthMap

      public TLcdWMMMagneticNorthMap()
      Constructs a new TLcdWMMMagneticNorthMap. The data file(s) should be set before all functionality of this object is available. Call setDataFileName or setDataFileNames before attempting to retrieve magnetic north parameters.

    • TLcdWMMMagneticNorthMap

      public TLcdWMMMagneticNorthMap(String aDataFileName)
      Constructs a new TLcdWMMMagneticNorthMap ready to use, for a single data file.
      Parameters:
      aDataFileName - The data file name for this object.
      Throws:
      IllegalArgumentException - when the file can't be found.

    • TLcdWMMMagneticNorthMap

      public TLcdWMMMagneticNorthMap(String[] aDataFileNames) throws IllegalArgumentException
      Constructor for a TLcdWMMMagneticNorthMap, initialized with a number of consecutive data files.
      Parameters:
      aDataFileNames - a list of filenames for the different WMM data files to be taken into account.
      Throws:
      IllegalArgumentException - When the valid date ranges for the passed data files aren't consecutive, or when one of the files can't be found.

  • Method Details

    • getDataFileName

      public String getDataFileName()
      Returns the file name of the data file currently used to base the calculations on.
      Returns:
      The file name of the data file currently used to base the calculations on
      See Also:

    • setDataFileName

      public void setDataFileName(String aDataFileName) throws IllegalArgumentException
      Sets the file name of the data file to be used. Refer to setDataFileNames(java.lang.String[]) when using multiple data files.
      Parameters:
      aDataFileName - The file name relative to the classpath
      Throws:
      IllegalArgumentException - when the file can't be found.
      See Also:

    • getDataFileNames

      public String[] getDataFileNames()
      Returns the uses data file names.
      Returns:
      the list of available data file names.

    • setDataFileNames

      public void setDataFileNames(String[] aDataFileNames) throws IllegalArgumentException
      Sets the list of data files to use. Warning: Make sure there are no holes in the total range of valid dates for the separate data files. Do not, for instance, pass a WMM file for 2000-2005 and one for 2010-2015 and omit the file for 2005-2010. The map will still work for the available life spans, but between getBeginValidDate() and getEndValidDate(), there will be a range of dates that will cause exceptions when used with this map.
      Parameters:
      aDataFileNames - A list of data file names relative to the classpath.
      Throws:
      IllegalArgumentException - When the valid date ranges for the passed data files aren't consecutive, or when one of the files can't be found.

    • retrieveDeclinationAt

      public float retrieveDeclinationAt(ILcdPoint aPoint)
      Description copied from interface: ILcdMagneticNorthMap
      Given a point (and implicitly a time value via setDate()), this method calculates the declination of the magnetic north vector.
      Specified by:
      retrieveDeclinationAt in interface ILcdMagneticNorthMap
      Parameters:
      aPoint - The point on the globe, the reference is World Geodetic System 1984 (WGS 84)
      Returns:
      the declination in degrees at the given point

    • retrieveInclinationAt

      public float retrieveInclinationAt(ILcdPoint aPoint)
      Description copied from interface: ILcdMagneticNorthMap
      Given a point (and implicitly a time value via setDate()), this method calculates the inclination of the magnetic north vector.
      Specified by:
      retrieveInclinationAt in interface ILcdMagneticNorthMap
      Parameters:
      aPoint - The point on the globe, the reference is World Geodetic System 1984 (WGS 84)
      Returns:
      the inclination in degrees at the given point

    • retrieveTotalIntensityAt

      public float retrieveTotalIntensityAt(ILcdPoint aPoint)
      Description copied from interface: ILcdMagneticNorthMap
      Given a point (and implicitly a time value via setDate()), this method calculates the total intensity of the magnetic north vector.
      Specified by:
      retrieveTotalIntensityAt in interface ILcdMagneticNorthMap
      Parameters:
      aPoint - The point on the globe, the reference is World Geodetic System 1984 (WGS 84)
      Returns:
      the total intensity in nanoTesla (nT) at the given point

    • clone

      public Object clone() throws CloneNotSupportedException
      Specified by:
      clone in interface ILcdMagneticNorthMap
      Throws:
      CloneNotSupportedException
      See Also:

    • isIgnoreModelLifeSpan

      public boolean isIgnoreModelLifeSpan()
      Returns true if the model lifespan is ignored, false otherwise.
      Returns:
      true if the model lifespan is ignored, false otherwise.

    • setIgnoreModelLifeSpan

      public void setIgnoreModelLifeSpan(boolean aIgnoreModelLifeSpan)
      With this method one set to ignore or to not ignore the model life span. See above for more info.
      Parameters:
      aIgnoreModelLifeSpan - true if the model life span should be ignored, false otherwise.

    • getModelName

      public String getModelName()
      Description copied from interface: ILcdMagneticNorthMap
      Returns the name of the model.
      Specified by:
      getModelName in interface ILcdMagneticNorthMap
      Returns:
      the name of the model

    • getShortModelName

      public String getShortModelName()
      Description copied from interface: ILcdMagneticNorthMap
      Returns the abbreviated model name.
      Specified by:
      getShortModelName in interface ILcdMagneticNorthMap
      Returns:
      the abbreviated model name

    • setDate

      public void setDate(Calendar aDate) throws IllegalArgumentException
      Sets the date to retrieve the magnetic north at.
      Specified by:
      setDate in interface ILcdMagneticNorthMap
      Parameters:
      aDate - The date, isValidDate(aDate) must be true.
      Throws:
      IllegalArgumentException - when isIgnoreModelLifeSpan() returns false and the date passed falls outside the life span for all available data files.
      See Also:

    • getBeginValidDate

      public Calendar getBeginValidDate()
      Return the first date value for which this map can retrieve magnetic north.
      Specified by:
      getBeginValidDate in interface ILcdMagneticNorthMap
      Returns:
      the first date value for which this map can retrieve magnetic north

    • getEndValidDate

      public Calendar getEndValidDate()
      Return the last date value for which this map can retrieve magnetic north.
      Specified by:
      getEndValidDate in interface ILcdMagneticNorthMap
      Returns:
      the last date value for which this map can retrieve magnetic north

    • getDate

      public Calendar getDate()
      Returns the current date set to this map.
      Specified by:
      getDate in interface ILcdMagneticNorthMap
      Returns:
      The current date set to this map.
      See Also:

    • isValidDate

      public boolean isValidDate(Calendar aDate)
      Checks whether the given date is a valid date for this map.
      Specified by:
      isValidDate in interface ILcdMagneticNorthMap
      Parameters:
      aDate - the date to check the validity for.
      Returns:
      true if getBeginValidDate() <= aDate <= getEndValidDate(), false otherwise.

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the input stream factory to load the data.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - an InputStream factory that creates input streams to load the magnetic north data.
      See Also:

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Returns the currently used input stream factory.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the currently used input stream factory.

    • getValidDateClosestToToday

      public Calendar getValidDateClosestToToday()

    • convertCalendarToDecimalTime

      public static float convertCalendarToDecimalTime(Calendar aTime)
      Converts a Calendar to a decimal year format. Only uses year, month and day. Hours and seconds are ignored.

    • convertDecimalTimeToCalendar

      public static Calendar convertDecimalTimeToCalendar(float aDecimalTime)
      Converts a decimal year format to a Calendar. Only uses year. Month, day, hours and seconds are ignored.