TLESeries.java

/* Copyright 2002-2017 CS Systèmes d'Information
 * Licensed to CS Systèmes d'Information (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * CS licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.orekit.propagation.analytical.tle;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.Set;
import java.util.SortedSet;
import java.util.TreeSet;

import org.orekit.data.DataLoader;
import org.orekit.data.DataProvidersManager;
import org.orekit.errors.OrekitException;
import org.orekit.errors.OrekitMessages;
import org.orekit.time.AbsoluteDate;
import org.orekit.time.ChronologicalComparator;
import org.orekit.time.TimeStamped;
import org.orekit.utils.PVCoordinates;

/** This class reads and handles series of TLEs for one space object.
 *  <p>
 *  TLE data is read using the standard Orekit mechanism based on a configured
 *  {@link DataProvidersManager DataProvidersManager}. This means TLE data may
 *  be retrieved from many different storage media (local disk files, remote servers,
 *  database ...).
 *  </p>
 *  <p>
 *  This class provides bounded ephemerides by finding the best initial TLE to
 *  propagate and then handling the propagation.
 *  </p>
 *
 * @see TLE
 * @see DataProvidersManager
 * @author Fabien Maussion
 * @author Luc Maisonobe
 * @deprecated as of 9.0, this class is deprecated without replacement. The file format
 * used was considered to be too specific and the API not really well designed. Users are
 * encouraged to use their own parser for series of TLE
 */
@Deprecated
public class TLESeries implements DataLoader {

    /** Default supported files name pattern. */
    private static final String DEFAULT_SUPPORTED_NAMES = ".*\\.tle$";

    /** Regular expression for supported files names. */
    private final String supportedNames;

    /** Available satellite numbers. */
    private final Set<Integer> availableSatNums;

    /** Set containing all TLE entries. */
    private final SortedSet<TimeStamped> tles;

    /** Satellite number used for filtering. */
    private int filterSatelliteNumber;

    /** Launch year used for filtering (all digits). */
    private int filterLaunchYear;

    /** Launch number used for filtering. */
    private int filterLaunchNumber;

    /** Launch piece used for filtering. */
    private String filterLaunchPiece;

    /** Previous TLE in the cached selection. */
    private TLE previous;

    /** Next TLE in the cached selection. */
    private TLE next;

    /** Last used TLE. */
    private TLE lastTLE;

    /** Associated propagator. */
    private TLEPropagator lastPropagator;

    /** Date of the first TLE. */
    private AbsoluteDate firstDate;

    /** Date of the last TLE. */
    private AbsoluteDate lastDate;

    /** Indicator for non-TLE extra lines. */
    private final boolean ignoreNonTLELines;

    /** Simple constructor with a TLE file.
     * <p>This constructor does not load any data by itself. Data must be
     * loaded later on by calling one of the {@link #loadTLEData()
     * loadTLEData()} method, the {@link #loadTLEData(int)
     * loadTLEData(filterSatelliteNumber)} method or the {@link #loadTLEData(int,
     * int, String) loadTLEData(filterLaunchYear, filterLaunchNumber, filterLaunchPiece)} method.<p>
     * @param supportedNames regular expression for supported files names
     * (if null, a default pattern matching files with a ".tle" extension will be used)
     * @param ignoreNonTLELines if true, extra non-TLE lines are silently ignored,
     * if false an exception will be generated when such lines are encountered
     * @see #loadTLEData()
     * @see #loadTLEData(int)
     * @see #loadTLEData(int, int, String)
     */
    public TLESeries(final String supportedNames, final boolean ignoreNonTLELines) {

        this.supportedNames    = (supportedNames == null) ? DEFAULT_SUPPORTED_NAMES : supportedNames;
        availableSatNums       = new TreeSet<Integer>();
        this.ignoreNonTLELines = ignoreNonTLELines;
        filterSatelliteNumber  = -1;
        filterLaunchYear       = -1;
        filterLaunchNumber     = -1;
        filterLaunchPiece      = null;

        tles     = new TreeSet<TimeStamped>(new ChronologicalComparator());
        previous = null;
        next     = null;

    }

    /** Load TLE data for a specified object.
     * <p>The TLE data already loaded in the instance will be discarded
     * and replaced by the newly loaded data.</p>
     * <p>The filtering values will be automatically set to the first loaded
     * satellite. This feature is useful when the satellite selection is
     * already set up by either the instance configuration (supported file
     * names) or by the {@link DataProvidersManager data providers manager}
     * configuration and the local filtering feature provided here can be ignored.</p>
     * @exception OrekitException if some data can't be read, some
     * file content is corrupted or no TLE data is available
     * @see #loadTLEData(int)
     * @see #loadTLEData(int, int, String)
     */
    public void loadTLEData() throws OrekitException {

        availableSatNums.clear();

        // set the filtering parameters
        filterSatelliteNumber = -1;
        filterLaunchYear      = -1;
        filterLaunchNumber    = -1;
        filterLaunchPiece     = null;

        // load the data from the configured data providers
        tles.clear();
        previous = null;
        next     = null;
        DataProvidersManager.getInstance().feed(supportedNames, this);
        if (tles.isEmpty()) {
            throw new OrekitException(OrekitMessages.NO_TLE_DATA_AVAILABLE);
        }

    }

    /** Get the available satellite numbers.
     * @return available satellite numbers
     * @throws OrekitException if some data can't be read, some
     * file content is corrupted or no TLE data is available
     */
    public Set<Integer> getAvailableSatelliteNumbers() throws OrekitException {
        if (availableSatNums.isEmpty()) {
            loadTLEData();
        }
        return availableSatNums;
    }

    /** Load TLE data for a specified object.
     * <p>The TLE data already loaded in the instance will be discarded
     * and replaced by the newly loaded data.</p>
     * <p>Calling this method with the satellite number set to a negative value,
     * is equivalent to call {@link #loadTLEData()}.</p>
     * @param satelliteNumber satellite number
     * @exception OrekitException if some data can't be read, some
     * file content is corrupted or no TLE data is available for the selected object
     * @see #loadTLEData()
     * @see #loadTLEData(int, int, String)
     */
    public void loadTLEData(final int satelliteNumber) throws OrekitException {

        if (satelliteNumber < 0) {
            // no filtering at all
            loadTLEData();
        } else {
            // set the filtering parameters
            filterSatelliteNumber = satelliteNumber;
            filterLaunchYear      = -1;
            filterLaunchNumber    = -1;
            filterLaunchPiece     = null;

            // load the data from the configured data providers
            tles.clear();
            previous = null;
            next     = null;
            DataProvidersManager.getInstance().feed(supportedNames, this);
            if (tles.isEmpty()) {
                throw new OrekitException(OrekitMessages.NO_TLE_FOR_OBJECT, satelliteNumber);
            }
        }

    }

    /** Load TLE data for a specified object.
     * <p>The TLE data already loaded in the instance will be discarded
     * and replaced by the newly loaded data.</p>
     * <p>Calling this method with either the launch year or the launch number
     * set to a negative value, or the launch piece set to null or an empty
     * string are all equivalent to call {@link #loadTLEData()}.</p>
     * @param launchYear launch year (all digits)
     * @param launchNumber launch number
     * @param launchPiece launch piece
     * @exception OrekitException if some data can't be read, some
     * file content is corrupted or no TLE data is available for the selected object
     * @see #loadTLEData()
     * @see #loadTLEData(int)
     */
    public void loadTLEData(final int launchYear, final int launchNumber,
                            final String launchPiece) throws OrekitException {

        if ((launchYear < 0) || (launchNumber < 0) ||
            (launchPiece == null) || (launchPiece.length() == 0)) {
            // no filtering at all
            loadTLEData();
        } else {
            // set the filtering parameters
            filterSatelliteNumber = -1;
            filterLaunchYear      = launchYear;
            filterLaunchNumber    = launchNumber;
            filterLaunchPiece     = launchPiece;

            // load the data from the configured data providers
            tles.clear();
            previous = null;
            next     = null;
            DataProvidersManager.getInstance().feed(supportedNames, this);
            if (tles.isEmpty()) {
                throw new OrekitException(OrekitMessages.NO_TLE_FOR_LAUNCH_YEAR_NUMBER_PIECE,
                                          launchYear, launchNumber, launchPiece);
            }
        }

    }

    /** {@inheritDoc} */
    public boolean stillAcceptsData() {
        return tles.isEmpty();
    }

    /** {@inheritDoc} */
    public void loadData(final InputStream input, final String name)
        throws IOException, OrekitException {

        final BufferedReader r = new BufferedReader(new InputStreamReader(input, "UTF-8"));
        try {

            int lineNumber     = 0;
            String pendingLine = null;
            for (String line = r.readLine(); line != null; line = r.readLine()) {

                ++lineNumber;

                if (pendingLine == null) {

                    // we must wait for the second line
                    pendingLine = line;

                } else {

                    // safety checks
                    if (!TLE.isFormatOK(pendingLine, line)) {
                        if (ignoreNonTLELines) {
                            // just shift one line
                            pendingLine = line;
                            continue;
                        } else {
                            throw new OrekitException(OrekitMessages.NOT_TLE_LINES,
                                                      lineNumber - 1, lineNumber, pendingLine, line);
                        }
                    }

                    final TLE tle = new TLE(pendingLine, line);

                    if (filterSatelliteNumber < 0) {
                        if ((filterLaunchYear < 0) ||
                            ((tle.getLaunchYear()   == filterLaunchYear) &&
                             (tle.getLaunchNumber() == filterLaunchNumber) &&
                             tle.getLaunchPiece().equals(filterLaunchPiece))) {
                            // we now know the number of the object to load
                            filterSatelliteNumber = tle.getSatelliteNumber();
                        }
                    }

                    availableSatNums.add(tle.getSatelliteNumber());

                    if (tle.getSatelliteNumber() == filterSatelliteNumber) {
                        // accept this TLE
                        tles.add(tle);
                    }

                    // we need to wait for two new lines
                    pendingLine = null;

                }

            }

            if ((pendingLine != null) && !ignoreNonTLELines) {
                // there is an unexpected last line
                throw new OrekitException(OrekitMessages.MISSING_SECOND_TLE_LINE,
                                          lineNumber, pendingLine);
            }

        } finally {
            r.close();
        }

    }

    /** Get the extrapolated position and velocity from an initial date.
     * For a good precision, this date should not be too far from the range :
     * [{@link #getFirstDate() first date} ; {@link #getLastDate() last date}].
     * @param date the final date
     * @return the final PVCoordinates
     * @exception OrekitException if the underlying propagator cannot be initialized
     */
    public PVCoordinates getPVCoordinates(final AbsoluteDate date)
        throws OrekitException {
        final TLE toExtrapolate = getClosestTLE(date);
        if (toExtrapolate != lastTLE) {
            lastTLE = toExtrapolate;
            lastPropagator = TLEPropagator.selectExtrapolator(lastTLE);
        }
        return lastPropagator.getPVCoordinates(date);
    }

    /** Get the closest TLE to the selected date.
     * @param date the date
     * @return the TLE that will suit the most for propagation.
     */
    public TLE getClosestTLE(final AbsoluteDate date) {

        //  don't search if the cached selection is fine
        if ((previous != null) && (date.durationFrom(previous.getDate()) >= 0) &&
            (next     != null) && (date.durationFrom(next.getDate())     <= 0)) {
            // the current selection is already good
            if (next.getDate().durationFrom(date) > date.durationFrom(previous.getDate())) {
                return previous;
            } else {
                return next;
            }
        }
        // reset the selection before the search phase
        previous  = null;
        next      = null;
        final SortedSet<TimeStamped> headSet = tles.headSet(date);
        final SortedSet<TimeStamped> tailSet = tles.tailSet(date);


        if (headSet.isEmpty()) {
            return (TLE) tailSet.first();
        }
        if (tailSet.isEmpty()) {
            return (TLE) headSet.last();
        }
        previous = (TLE) headSet.last();
        next = (TLE) tailSet.first();

        if (next.getDate().durationFrom(date) > date.durationFrom(previous.getDate())) {
            return previous;
        } else {
            return next;
        }
    }

    /** Get the start date of the series.
     * @return the first date
     */
    public AbsoluteDate getFirstDate() {
        if (firstDate == null) {
            firstDate = tles.first().getDate();
        }
        return firstDate;
    }

    /** Get the last date of the series.
     * @return the end date
     */
    public AbsoluteDate getLastDate() {
        if (lastDate == null) {
            lastDate = tles.last().getDate();
        }
        return lastDate;
    }

    /** Get the first TLE.
     * @return first TLE
     */
    public TLE getFirst() {
        return (TLE) tles.first();
    }

    /** Get the last TLE.
     * @return last TLE
     */
    public TLE getLast() {
        return (TLE) tles.last();
    }

}