ucar.nc2.dt.GridCoordSystem Maven / Gradle / Ivy
The newest version!
/*
* Copyright (c) 1998-2018 John Caron and University Corporation for Atmospheric Research/Unidata
* See LICENSE for license information.
*/
package ucar.nc2.dt;
import ucar.nc2.dataset.*;
import ucar.nc2.Dimension;
import ucar.nc2.time.CalendarDate;
import ucar.nc2.time.CalendarDateRange;
import ucar.nc2.units.DateRange;
import ucar.ma2.InvalidRangeException;
import ucar.ma2.Range;
import ucar.unidata.geoloc.LatLonPoint;
import java.util.Collection;
import java.util.Formatter;
import java.util.List;
/**
* A Coordinate System for gridded data. Assume:
*
* - X and Y are 1 or 2 dimensional
*
- T is 1 or 2 dimensional. The 2D case is that it depends on runtime.
*
- We can create Dates out of the T and RT coordinate values.
*
- Z, E, RT are 1-dimensional
*
- An optional VerticalTransform can provide a height or pressure coordinate that may be 1-4 dimensional.
*
*
*
* @author caron
*/
public interface GridCoordSystem {
/*
* LOOK
* We could insist on one dimensional X, Y, Z, T, and treat optional HorizontalTransform the same as
* VerticalTransform.
* Its job would be to provide lat(x,y) and lon(x,y) arrays.
*/
/**
* The name of the Grid Coordinate System, consisting of the list of coordinate axes, separated by blanks.
*
* @return name of the Grid Coordinate System
*/
String getName();
/**
* Get the list of dimensions used by any of the Axes in the Coordinate System.
*
* @return List of Dimension
*/
Collection getDomain();
// axes
/**
* Get the list of all axes.
*
* @return List of CoordinateAxis.
*/
List getCoordinateAxes();
/**
* True if all axes are 1 dimensional.
*
* @return true if all axes are 1 dimensional.
*/
boolean isProductSet();
/**
* Get the X axis. May be 1 or 2 dimensional.
*
* @return X CoordinateAxis, may not be null.
*/
CoordinateAxis getXHorizAxis();
/**
* Get the Y axis. May be 1 or 2 dimensional.
*
* @return Y CoordinateAxis, may not be null.
*/
CoordinateAxis getYHorizAxis();
/**
* Get the Z axis. Must be 1 dimensional.
*
* @return Y CoordinateAxis, may be null.
*/
CoordinateAxis1D getVerticalAxis();
/**
* Get the Time axis, if it exists. May be 1 or 2 dimensional.
* If 1D, will be a CoordinateAxis1DTime. If 2D, then you can use getTimeAxisForRun().
* A time coordinate must be a udunit date or ISO String, so it can always be converted to a Date.
* Typical meaning is the date of measurement or valid forecast time.
*
* @return the time coordinate axis, may be null.
*/
CoordinateAxis getTimeAxis();
/**
* Get the ensemble axis. Must be 1 dimensional.
* Typical meaning is an enumeration of ensemble Model runs.
*
* @return ensemble CoordinateAxis, may be null.
*/
CoordinateAxis1D getEnsembleAxis();
/**
* Get the RunTime axis. Must be 1 dimensional.
* A runtime coordinate must be a udunit date or ISO String, so it can always be converted to a Date.
* Typical meaning is the date that a Forecast Model Run is made.
*
* @return RunTime CoordinateAxis, may be null.
*/
CoordinateAxis1DTime getRunTimeAxis();
// transforms
/**
* Get the list of all CoordinateTransforms.
*
* @return List of CoordinateTransform.
*/
List getCoordinateTransforms();
/**
* Get the Projection CoordinateTransform. It must exist if !isLatLon().
*
* @return ProjectionCT or null.
*/
ProjectionCT getProjectionCT();
/**
* Get the Projection that performs the transform math.
* Same as getProjectionCT().getProjection().
*
* @return ProjectionImpl or null.
* @deprecated this will return Projection, not ProjectionImpl in 6.
*/
ucar.unidata.geoloc.ProjectionImpl getProjection();
/**
* Use the bounding box to set the defaule map are of the projection.
* This can be expensive if its a 2D coordinate system.
*/
void setProjectionBoundingBox();
/**
* Get the Vertical CoordinateTransform, it it exists.
*
* @return VerticalCT or null.
*/
VerticalCT getVerticalCT();
/**
* Get the VerticalTransform that performs the transform math.
* Same as getVerticalCT().getVerticalTransform().
*
* @return VerticalTransform or null.
*/
ucar.unidata.geoloc.vertical.VerticalTransform getVerticalTransform();
// horiz
/**
* Does this use lat/lon horizontal axes?
* If not, then the horizontal axes are GeoX, GeoY, and there must be a Projection defined.
*
* @return true if lat/lon horizontal axes
*/
boolean isLatLon();
/**
* Is this a global coverage over longitude ?
*
* @return true if isLatLon and longitude extent >= 360 degrees
*/
boolean isGlobalLon();
/**
* Get horizontal bounding box in lat, lon coordinates.
* For projection, only an approximation based on corners.
*
* @return LatLonRect bounding box.
*/
ucar.unidata.geoloc.LatLonRect getLatLonBoundingBox();
/**
* Get horizontal bounding box in projection coordinates.
* For lat/lon, the ProjectionRect has units of degrees north and east.
*
* @return ProjectionRect bounding box.
*/
ucar.unidata.geoloc.ProjectionRect getBoundingBox();
/**
* True if both X and Y axes are 1 dimensional and are regularly spaced.
*
* @return true if both X and Y axes are 1 dimensional and are regularly spaced.
*/
boolean isRegularSpatial();
/**
* Get Index Ranges for the given lat, lon bounding box.
* For projection, only an approximation based on corners.
* Must have CoordinateAxis1D or 2D for x and y axis.
*
* @param llbb a lat/lon bounding box.
* @return list of 2 Range objects, first y then x.
* @throws ucar.ma2.InvalidRangeException if llbb generates bad ranges
*/
java.util.List getRangesFromLatLonRect(ucar.unidata.geoloc.LatLonRect llbb) throws InvalidRangeException;
/**
* Given a point in x,y coordinate space, find the x,y indices.
*
* @param x_coord position in x coordinate space, ie, units of getXHorizAxis().
* @param y_coord position in y coordinate space, ie, units of getYHorizAxis().
* @param result optionally pass in the result array to use.
* @return int[2], 0=x, 1=y indices of the point. These will be -1 if out of range.
*/
int[] findXYindexFromCoord(double x_coord, double y_coord, int[] result);
/**
* Given a point in x,y coordinate space, find the x,y indices.
* If outside the range, the closest point is returned
*
* @param x_coord position in x coordinate space, ie, units of getXHorizAxis().
* @param y_coord position in y coordinate space, ie, units of getYHorizAxis().
* @param result optionally pass in the result array to use.
* @return int[2], 0=x, 1=y indices of the point.
*/
int[] findXYindexFromCoordBounded(double x_coord, double y_coord, int[] result);
/**
* Given a lat,lon point, find the x,y index of the containing grid point.
*
* @param lat latitude position.
* @param lon longitude position.
* @param result put result in here, may be null
* @return int[2], 0=x,1=y indices in the coordinate system of the point. These will be -1 if out of range.
*/
int[] findXYindexFromLatLon(double lat, double lon, int[] result);
/**
* Given a lat,lon point, find the x,y index of the containing grid point.
* If outside the range, the closest point is returned
*
* @param lat latitude position.
* @param lon longitude position.
* @param result return result here, may be null
* @return int[2], 0=x,1=y indices in the coordinate system of the point.
*/
int[] findXYindexFromLatLonBounded(double lat, double lon, int[] result);
/**
* Get the Lat/Lon coordinates of the midpoint of a grid cell, using the x,y indices.
*
* @param xindex x index
* @param yindex y index
* @return lat/lon coordinate of the midpoint of the cell
*/
LatLonPoint getLatLon(int xindex, int yindex);
// vertical
/**
* True if increasing z coordinate values means "up" in altitude
*
* @return true if increasing z coordinate values means "up" in altitude
*/
boolean isZPositive();
// time
/**
* If there is a time coordinate, get the time covered.
*
* @return DateRange or null if no time coordinate
* @deprecated use getCalendarDateRange()
*/
DateRange getDateRange();
/**
* True if there is a Time Axis.
*
* @return true if there is a Time Axis.
*/
boolean hasTimeAxis();
/**
* True if there is a Time Axis and it is 1D.
*
* @return true if there is a Time Axis and it is 1D.
*/
boolean hasTimeAxis1D();
/**
* Get the Time axis, if it exists, and if its 1-dimensional.
*
* @return the time coordinate axis, may be null.
*/
CoordinateAxis1DTime getTimeAxis1D();
/**
* This is the case of a 2D time axis, which depends on the run index.
* A time coordinate must be a udunit date or ISO String, so it can always be converted to a Date.
*
* @param run_index which run?
* @return 1D time axis for that run. Null if not 2D time
*/
CoordinateAxis1DTime getTimeAxisForRun(int run_index);
List getCalendarDates();
CalendarDateRange getCalendarDateRange();
String getHorizStaggerType();
void show(Formatter buff, boolean showCoords);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy