%pointAt   Specify the target at which the satellite must point. The
%   attitude is constantly adjusted so that its yaw (body z) axis tracks
%   the desired target. The roll (body x) axis is aligned with the inertial
%   velocity vector by minimizing the angle between them (exact alignment
%   is usually geometrically impossible). When attitude timetable or
%   timeseries is used, the attitude attitude follows the specified
%   profile.
%
%   pointAt(SAT, COORDINATES) steers the satellites in the vector SAT
%   towards the geographical coordinates specified by COORDINATES. Specify
%   COORDINATES as a three-element vector, or a two-dimensional array.
%     - When specified as a three-element vector, the elements correspond
%       to the latitude, longitude, and altitude, in that order, and all
%       satellites are steered to point at this location.
%     - When COORDINATES is specified as an array, the number of rows must 
%       equal three. The number of columns must equal the number of
%       satellites in SAT. The rows correspond to the latitude, longitude,
%       and altitude, in that order, and each column represents the
%       pointing coordinates of the corresponding satellite in the vector
%       SAT. The latitudes and longitudes are specified in degrees and the
%       altitudes are specified in meters. They represent the height above
%       the surface of the Earth.
%
%   pointAt(SAT, TARGET) steers the satellites specified by SAT towards the
%   specified target TARGET. Input TARGET can be another satellite, 
%   platform, or  ground station, specified as a scalar or a vector.
%     - When specified as a scalar, all satellites point to the specified
%       TARGET.
%     - If TARGET is a vector, its length must equal the number of
%       satellites in SAT, and each element in TARGET represents the
%       pointing target of a satellite in SAT.
%
%   pointAt(SAT, "nadir") steers the satellites specified by the row vector
%   SAT towards the nadir direction. "nadir" is the default pointing
%   direction.
%
%   pointAt(SAT, ATTITUDETABLE) sets the attitude of the satellite SAT such
%   that it follows the attitude provided in ATTITUDETABLE. ATTITUDETABLE
%   is a MATLAB(R) <a href="matlab:help('timetable')">timetables</a> with
%   exactly one monotonically increasing column of rowTimes (datetime or
%   duration). If SAT contains a single satellite, the table must contain
%   one data column of scalar-first quaternions [1x4], or Z-Y-X Euler
%   angles [1x3] in degrees. If SAT is an array of satellites, each data 
%   row must contain either:
%       - Multiple columns, where each column contains data for an
%         individual satellite over time.
%       - One column of 2-D data, where the length of one dimension must
%         equal 3 or 4 (depending on whether Euler angles or quaternions
%         are used) and the remaining dimension must have length equal to
%         the number of satellites in SAT.
%       - One column of 3-D data, where the length of one dimension must
%         equal 3 or 4 (depending on whether Euler angles or quaternions
%         are used), one dimension is a singleton, and the remaining
%         dimension must have length equal to the number of satellites in
%         SAT.
%   Euler angles represent passive, intrinsic rotations using the Z-Y-X
%   rotation order. If the provided rowTimes are of type 'duration', time
%   values are measured relative to the current scenario StartTime
%   property. The function assumes that satellite attitudes represent the
%   transformation from the Geocentric Celestial Reference Frame (GCRF) to
%   the body frame, unless a "CoordinateFrame" name-value pair is provided.
%   For scenario timesteps outside of the time range of ATTITUDETABLE, the
%   function uses "nadir" by default unless name-value pair
%   "ExtrapolationMethod" is provided.
%
%   pointAt(SAT, ATTITUDETIMESERIES) sets the attitude of the satellite SAT
%   such that it follows the attitude provided in ATTITUDETIMESERIES.
%   ATTITUDETIMESERIES is a MATLAB(R) <a
%   href="matlab:help('timeseries')">timeseries</a> containing scalar-first
%   quaternions or Z-Y-X Euler angles in degrees. If the Data property of the
%   timeseries has two dimensions, the length of one dimension must equal 3
%   or 4 (depending on whether Euler angles or quaternions are used) and
%   the other dimension must align with the orientation of the time vector.
%   If SAT is an array of satellites, the Data property of the timeseries
%   must have three dimensions where the length of one dimension must equal
%   3 or 4 (depending on whether Euler angles or quaternions are used),
%   either the first or the last dimension must align with the orientation
%   of the time vector, and the remaining dimension must align with the
%   number of satellites in SAT. Euler angles represent passive, intrinsic
%   rotations using the Z-Y-X rotation order. When
%   'timeseries.TimeInfo.StartDate' is empty, time values are measured
%   relative to the current scenario StartTime property. The function
%   assumes that satellite attitudes represent the transformation from the
%   Geocentric Celestial Reference Frame (GCRF) to the body frame, unless a
%   "CoordinateFrame" name-value pair is provided. For scenario timesteps
%   outside of the time range of ATTITUDETABLE, the function uses "nadir"
%   by default unless name-value pair "ExtrapolationMethod" is provided.
%
%   pointAt name-value pairs:
%
%   CoordinateFrame - Coordinate frame of custom attitude inputs
%       (TIMETABLE or TIMESERIES), specified as a string scalar or 
%       character vector equal to "inertial", "ecef" or "ned". The 
%       default value is "inertial". CoordinateFrame is available only for 
%       custom attitude inputs.
%         - "inertial" interprets the provided attitude values as the
%           rotation from the Geocentric Celestial Reference Frame (GCRF)
%           to the Body frame.
%         - "ecef" interprets the provided attitude values as the rotation
%           from the Earth-Centered-Earth-Fixed (ECEF) frame to the Body
%           frame.
%         - "ned" interprets the provided attitude values as the rotation
%           from the North-East-Down (NED) frame to the Body frame.
%
%	ExtrapolationMethod - Default behavior for attitude, used by the 
%       scenario for scenario time steps that lie outside of the provided
%       custom attitude time range. If ExtrapolationMethod is not provided,
%       a warning is displayed when the scenario time is out of range of
%       the custom attitude time range and "nadir" is used by default.
%       ExtrapolationMethod is available only for custom attitude inputs.
%         - "nadir" sets the attitude of the satellite SAT such that 
%           its yaw axis points in the nadir direction.
%         - "fixed" keeps the attitude constant with respect to the GCRF at
%           the closest time value for which data was provided in the
%           custom attitude data.
%
%   Format - Format of the attitude data provided, specified as a string 
%       scalar or character vector equal to "quaternion" or "euler".
%       Format is available only for custom attitude inputs. The 
%       default value is "quaternion".
%         - "quaternion" interprets the provided attitude values as
%         scalar-first quaternions. Quaternions represent passive rotations
%         from "CoordinateFrame" to the Body frame.
%         - "euler" interprets the provided attitude values as Euler
%         angles in degrees. Euler angles represent passive, intrinsic
%         rotations from "CoordinateFrame" to the Body frame using the
%         Z-Y-X rotation order and are provided in that order.
%
%   When AutoSimulate of the satellite scenario is false, you can call
%   pointAt as long as SimulationStatus is NotStarted or InProgress.
%
%   % Examples
%
%   % Example 1: Point the satellites added from a TLE file at a specified
%   % geographical coordinate
%
%   % Create a satelliteScenario object.
%   startTime = datetime(2020,5,9,12,0,0);
%   stopTime = startTime + days(1);
%   sampleTime = 60;
%   sc = satelliteScenario(startTime,stopTime,sampleTime);
%
%   % Add a satellite to the scenario from a TLE file.
%   tleFile = "eccentricOrbitSatellite.tle";
%   sat = satellite(sc,tleFile);
%
%   % Add a conical sensor to the satellite.
%   maxViewAngle = 10; % degrees
%   c = conicalSensor(sat,"MaxViewAngle",maxViewAngle);
%
%   % Specify the geographical coordinate at which the satellite must
%   % point.
%   latitude = 40; % degrees
%   longitude = -90; % degrees
%   altitude = 0; % meters
%   geographicalCoordinate = [latitude; longitude; altitude];
%
%   % Point the satellite at the specified geographical coordinate.
%   pointAt(sat,geographicalCoordinate);
%
%   % Visualize the field of view of the conical sensor. Because the 
%   % satellite is pointing at the specified geographic coordinates, the 
%   % field of view contour is distorted.
%   satelliteScenarioViewer(sc);
%   fieldOfView(c);
%
%   % Animate the scenario. The shape of the field of view contour keeps 
%   % getting updated because the attitude of the satellite is continuously
%   % updated to make its yaw axis track the specified geographical
%   % coordinate.
%   play(sc);
%
%   % Example 2: Point the satellite added from a TLE file at a ground
%   % station
%
%   % Create a satelliteScenario object.
%   startTime = datetime(2020,5,9,12,0,0);
%   stopTime = startTime + days(1);
%   sampleTime = 60;
%   sc = satelliteScenario(startTime,stopTime,sampleTime);
%
%   % Add a satellite to the scenario from a TLE file.
%   tleFile = "eccentricOrbitSatellite.tle";
%   sat = satellite(sc,tleFile);
%
%   % Add a conical sensor to the satellite.
%   maxViewAngle = 10; % degrees
%   c = conicalSensor(sat,"MaxViewAngle",maxViewAngle);
%
%   % Add a ground station to the scenario using default properties.
%   gs = groundStation(sc);
%
%   % Point the satellite at the ground station.
%   pointAt(sat,gs);
%
%   % Visualize the field of view. Because the satellite is tracking the
%   % ground station, the field of view contour is distorted.
%   satelliteScenarioViewer(sc);
%   fieldOfView(c);
%
%   % Animate the scenario. The shape of the field of view contour keeps 
%   % getting updated because the attitude of the satellite is continuously
%   % updated to track the ground station.
%   play(sc);
%
%   % Example 3: Point the satellite toward the nadir direction after
%   % pointing it at a ground station
%
%   % Create a satelliteScenario object.
%   startTime = datetime(2020,5,9,12,0,0);
%   stopTime = startTime + days(1);
%   sampleTime = 60;
%   sc = satelliteScenario(startTime,stopTime,sampleTime);
%
%   % Add satellite to the scenario from a TLE file.
%   tleFile = "eccentricOrbitSatellite.tle";
%   sat = satellite(sc,tleFile);
%
%   % Add a conical sensor to the satellite.
%   maxViewAngle= 10; % degrees
%   c = conicalSensor(sat,"MaxViewAngle",maxViewAngle);
%
%   % Add a ground station to the scenario using default properties.
%   gs = groundStation(sc);
%
%   % Point the satellite at the ground station.
%   pointAt(sat, gs);
%
%   % Visualize the field of view. Because the satellite is pointing at the
%   % ground station, the field of view contour is distorted.
%   satelliteScenarioViewer(sc);
%   fieldOfView(c);
%
%   % Animate the scenario. The shape of the field of view contour keeps 
%   % getting updated because the attitude of the satellite is continuously
%   % updated to track the ground station.
%   play(sc);
%
%   % Point the satellite toward the nadir direction.
%   pointAt(sat,"nadir");
%
%   % Visualize the field of view. Because the satellite is pointing toward
%   % nadir, the field of view contour is nearly circular.
%   fieldOfView(c);
%
%   % Animate the scenario. The shape of the field of view contour 
%   % continues to remain near-circular because the satellite is pointing 
%   % towards toward the nadir direction.
%   play(sc);
%
%   See also <a href="matlab:help('satelliteScenario.satellite')">satellite</a>

 
%   Copyright 2020-2023 The MathWorks, Inc.

