AggregatedPVCoordinatesProvider

/* Copyright 2002-2025 Joseph Reed
 * Licensed to CS GROUP (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * Joseph Reed 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.utils;

import java.util.Objects;

import org.hipparchus.geometry.euclidean.threed.Vector3D;
import org.orekit.errors.OrekitException;
import org.orekit.errors.OrekitMessages;
import org.orekit.frames.Frame;
import org.orekit.time.AbsoluteDate;

/** Aggregate multiple {@link PVCoordinatesProvider} instances together.
 * <p>
 * This can be used to describe an aircraft or surface vehicle.
 * </p>
 * @author Joe Reed
 * @since 11.3
 */
public class AggregatedPVCoordinatesProvider implements PVCoordinatesProvider {

    /** Map of provider instances by transition time. */
    private final TimeSpanMap<PVCoordinatesProvider> pvProvMap;

    /** Earliest date at which {@link #getPVCoordinates(AbsoluteDate, Frame)} will return a valid result. */
    private final AbsoluteDate minDate;

    /** Latest date at which {@link #getPVCoordinates(AbsoluteDate, Frame)} will return a valid result. */
    private final AbsoluteDate maxDate;

    /** Class constructor.
     * <p>
     * Note the provided {@code map} is used directly. Modification of the
     * map after calling this constructor may result in undefined behavior.
     * </p>
     * @param map the map of {@link PVCoordinatesProvider} instances by time.
     */
    public AggregatedPVCoordinatesProvider(final TimeSpanMap<PVCoordinatesProvider> map) {
        this(map, null, null);
    }

    /** Class constructor.
     * <p>
     * Note the provided {@code map} is used directly. Modification of the
     * map after calling this constructor may result in undefined behavior.
     * </p>
     * @param map the map of {@link PVCoordinatesProvider} instances by time.
     * @param minDate the earliest valid date, {@code null} if always valid
     * @param maxDate the latest valid date, {@code null} if always valid
     */
    public AggregatedPVCoordinatesProvider(final TimeSpanMap<PVCoordinatesProvider> map,
                                           final AbsoluteDate minDate, final AbsoluteDate maxDate) {
        this.pvProvMap = Objects.requireNonNull(map, "PVCoordinatesProvider map must be non-null");
        this.minDate = minDate == null ? AbsoluteDate.PAST_INFINITY : minDate;
        this.maxDate = maxDate == null ? AbsoluteDate.FUTURE_INFINITY : maxDate;
    }

    /** Get the first date of the range.
     * @return the first date of the range
     */
    public AbsoluteDate getMinDate() {
        return minDate;
    }

    /** Get the last date of the range.
     * @return the last date of the range
     */
    public AbsoluteDate getMaxDate() {
        return maxDate;
    }

    @Override
    public Vector3D getPosition(final AbsoluteDate date, final Frame frame) {
        if (date.isBefore(minDate) || date.isAfter(maxDate)) {
            throw new OrekitException(OrekitMessages.OUT_OF_RANGE_DATE, date, minDate, maxDate);
        }
        return pvProvMap.get(date).getPosition(date, frame);
    }

    @Override
    public Vector3D getVelocity(final AbsoluteDate date, final Frame frame) {
        if (date.isBefore(minDate) || date.isAfter(maxDate)) {
            throw new OrekitException(OrekitMessages.OUT_OF_RANGE_DATE, date, minDate, maxDate);
        }
        return pvProvMap.get(date).getVelocity(date, frame);
    }

    @Override
    public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate date, final Frame frame) {
        if (date.isBefore(minDate) || date.isAfter(maxDate)) {
            throw new OrekitException(OrekitMessages.OUT_OF_RANGE_DATE, date, minDate, maxDate);
        }
        return pvProvMap.get(date).getPVCoordinates(date, frame);
    }

    /**
     * Builder class for {@link AggregatedPVCoordinatesProvider}.
     */
    public static class Builder {

        /** Time span map holding the incremental values. */
        private final TimeSpanMap<PVCoordinatesProvider> pvProvMap;

        /**
         * Create a builder using the {@link InvalidPVProvider} as the initial provider.
         */
        public Builder() {
            this(new InvalidPVProvider());
        }

        /**
         * Create a builder using the provided initial provider.
         *
         * @param initialProvider the inital provider
         */
        public Builder(final PVCoordinatesProvider initialProvider) {
            pvProvMap = new TimeSpanMap<>(initialProvider);
        }

        /** Add a {@link PVCoordinatesProvider} to the collection.
         * <p>
         * The provided date is the transition time, at which this provider will be used.
         * </p>
         * @param date the transition date
         * @param pvProv the provider
         * @param erasesLater if true, the entry erases all existing transitions that are later than {@code date}
         * @return this builder instance
         * @see TimeSpanMap#addValidAfter(Object, AbsoluteDate, boolean)
         */
        public Builder addPVProviderAfter(final AbsoluteDate date,
                                          final PVCoordinatesProvider pvProv,
                                          final boolean erasesLater) {
            pvProvMap.addValidAfter(pvProv, date, erasesLater);
            return this;
        }

        /** Add a {@link PVCoordinatesProvider} to the collection.
         * <p>
         * The provided date is the final transition time, before which this provider will be used.
         * </p>
         * @param date the transition date
         * @param pvProv the provider
         * @param erasesEarlier if true, the entry erases all existing transitions that are earlier than {@code date}
         * @return this builder instance
         * @see TimeSpanMap#addValidBefore(Object, AbsoluteDate, boolean)
         */
        public Builder addPVProviderBefore(final AbsoluteDate date, final PVCoordinatesProvider pvProv, final boolean erasesEarlier) {
            pvProvMap.addValidBefore(pvProv, date, erasesEarlier);
            return this;
        }

        /** Indicate the date before which the resulting PVCoordinatesProvider is invalid.
         *
         * @param firstValidDate first date at which the resuling provider should be valid
         * @return this instance
         */
        public Builder invalidBefore(final AbsoluteDate firstValidDate) {
            pvProvMap.addValidBefore(new InvalidPVProvider(), firstValidDate, true);
            return this;
        }

        /** Indicate the date after which the resulting PVCoordinatesProvider is invalid.
         *
         * @param lastValidDate last date at which the resuling provider should be valid
         * @return this instance
         */
        public Builder invalidAfter(final AbsoluteDate lastValidDate) {
            pvProvMap.addValidAfter(new InvalidPVProvider(), lastValidDate, true);
            return this;
        }

        /** Build the aggregated PVCoordinatesProvider.
         *
         * @return the new provider instance.
         */
        public AggregatedPVCoordinatesProvider build() {
            AbsoluteDate minDate = null;
            AbsoluteDate maxDate = null;
            // check the first span
            if (pvProvMap.getFirstTransition() != null) {
                if (pvProvMap.getFirstTransition().getBefore() instanceof InvalidPVProvider) {
                    minDate = pvProvMap.getFirstTransition().getDate();
                }
            }
            if (pvProvMap.getLastTransition() != null) {
                if (pvProvMap.getLastTransition().getAfter() instanceof InvalidPVProvider) {
                    maxDate = pvProvMap.getLastTransition().getDate();
                }
            }
            return new AggregatedPVCoordinatesProvider(pvProvMap, minDate, maxDate);
        }
    }

    /** Implementation of {@link PVCoordinatesProvider} that throws an {@link OrekitException} exception.
     *
     */
    public static class InvalidPVProvider implements PVCoordinatesProvider {

        /** Empty constructor.
         * <p>
         * This constructor is not strictly necessary, but it prevents spurious
         * javadoc warnings with JDK 18 and later.
         * </p>
         * @since 12.0
         */
        public InvalidPVProvider() {
            // nothing to do
        }

        @Override
        public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate date, final Frame frame) {
            throw new OrekitException(OrekitMessages.OUT_OF_RANGE_DATE, date);
        }

    }

}