edu.nrao.sss.astronomy
Class SkyPositionFilter

java.lang.Object
  edu.nrao.sss.astronomy.SkyPositionFilter

All Implemented Interfaces:

Filter<SkyPosition>

public class SkyPositionFilter
extends Object
implements Filter<SkyPosition>

A filter that operates on SkyPositions.

This filter allows you to select positions based on their latitudes, longitudes, and distances from some origin. In addition, this filter has special setCone methods that can be used separately or in conjunction with the typical min/max ranges available for latitude and longitude. That is, you could select only those positions that were both in a given cone search and within given min/max latitude/longitude values.

Revision Info:

$Revision: 1239 $

$Date: 2008-04-25 10:34:57 -0600 (Fri, 25 Apr 2008) $

$Author: dharland $ (last person to modify)

Since:

2006-06-27

Author:

David M. Harland

Field Summary

static Distance	ANY_DISTANCE A constant that may be used to indicate that the minimum or maximum distance is unbounded.
static Latitude	ANY_LATITUDE A constant that may be used to indicate that the minimum or maximum latitude is unbounded.
static Longitude	ANY_LONGITUDE A constant that may be used to indicate that the minimum or maximum longitude is unbounded.
static Date	CURRENT_TIME A constant that indicates the current time should be used when evaluating the information held by a position.

Constructor Summary

SkyPositionFilter()
Creates a new wide-open filter that allows all positions to pass.

Method Summary

boolean	allows(SkyPosition sp) Returns true if this filter allows the given position to pass through it.
boolean	blocks(SkyPosition sp) Returns true if this filter blocks the given position.
void	clearAll() Sets this filter to a wide-open state.
void	clearCone() Stops this filter from applying a cone search.
void	clearDistance() Sets the distance criterion to its wide-open state.
void	clearLatitude() Sets the latitude criterion to its wide-open state.
void	clearLongitude() Sets the longitude criterion to its wide-open state.
void	clearQueryTime() Sets this filter so that it will use the current time when querying positions sent to the allows(SkyPosition) or blocks(SkyPosition) methods.
Collection<? extends SkyPosition>	removeAllBlockedParticlesFrom(Collection<? extends SkyPosition> flow) Removes from flow any position that is blocked by this filter.
void	setCone(Latitude centerLatitude, Longitude centerLongitude, Angle searchRadius) Sets this filter so that only positions within the cone described by the center latitude / longitude pair and the search radius may pass.
void	setCone(SkyPosition center, Angle searchRadius) Sets this filter so that only positions within the cone described by the center and the search radius may pass.
void	setDistance(Distance center, Distance halfWidth) Sets the distance range for this filter.
void	setDistanceRange(Distance min, Distance max) Sets the distance range for this filter.
void	setLatitude(Latitude center, Angle halfWidth) Sets the latitude range for this filter.
void	setLatitudeLongitudeRectangle(Latitude centerLatitude, Longitude centerLongitude, Angle halfWidth) Sets that latitude and longitude ranges for this filter.
void	setLatitudeRange(Latitude min, Latitude max) Sets the latitude range for this filter.
void	setLongitude(Longitude center, Angle halfWidth) Sets the longitude range for this filter.
void	setLongitudeRange(LongitudeInterval newInterval) Sets the longitude range for this filter.
void	setLongitudeRange(Longitude from, Longitude to) Sets the longitude range for this filter.
void	setQueryTime(Date time) Sets the date and time at which the filtered position is queried for its longitude, latitude, and distance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ANY_LONGITUDE

public static final Longitude ANY_LONGITUDE

A constant that may be used to indicate that the minimum or maximum longitude is unbounded.

ANY_LATITUDE

public static final Latitude ANY_LATITUDE

A constant that may be used to indicate that the minimum or maximum latitude is unbounded.

ANY_DISTANCE

public static final Distance ANY_DISTANCE

A constant that may be used to indicate that the minimum or maximum distance is unbounded.

CURRENT_TIME

public static final Date CURRENT_TIME

A constant that indicates the current time should be used when evaluating the information held by a position.

Constructor Detail

SkyPositionFilter

public SkyPositionFilter()

Creates a new wide-open filter that allows all positions to pass.

Method Detail

clearAll

public void clearAll()

Sets this filter to a wide-open state. After this call all filtering criteria will be in their wide-open states and this filter will allow all positions to pass.

clearCone

public void clearCone()

Stops this filter from applying a cone search.

See Also:

setCone(Latitude, Longitude, Angle)

clearLongitude

public void clearLongitude()

Sets the longitude criterion to its wide-open state.

See Also:

setLongitude(Longitude, Angle), setLongitudeRange(Longitude, Longitude)

clearLatitude

public void clearLatitude()

Sets the latitude criterion to its wide-open state.

See Also:

setLatitude(Latitude, Angle), setLatitudeRange(Latitude, Latitude)

clearDistance

public void clearDistance()

Sets the distance criterion to its wide-open state.

See Also:

setDistance(Distance, Distance), setDistanceRange(Distance, Distance)

clearQueryTime

public void clearQueryTime()

Sets this filter so that it will use the current time when querying positions sent to the allows(SkyPosition) or blocks(SkyPosition) methods.

setCone

public void setCone(SkyPosition center,
                    Angle searchRadius)

Sets this filter so that only positions within the cone described by the center and the search radius may pass. Clients may further narrow the search by explicitly setting minimum and maximum latitudes, longitudes, and distances.

This is a convenience method that is equivalent to calling:

   setCone(center.getLatitude(), center.getLongitude(), searchRadius);
 

Parameters:

center - the center of the search cone.

searchRadius - the radius of the cone. The radius may not be larger than one-quarter circle (e.g., 90 degrees). If it is, an illegal argument exception is thrown.

setCone

public void setCone(Latitude centerLatitude,
                    Longitude centerLongitude,
                    Angle searchRadius)

Sets this filter so that only positions within the cone described by the center latitude / longitude pair and the search radius may pass. Clients may further narrow the search by explicitly setting minimum and maximum latitudes, longitudes, and distances.

Parameters:

centerLatitude - the latitude of the center point of the cone.

centerLongitude - the longitude of the center point of the cone.

searchRadius - the radius of the cone. The radius may not be larger than one-quarter circle (e.g., 90 degrees). If it is, an illegal argument exception is thrown.

setLatitudeLongitudeRectangle

public void setLatitudeLongitudeRectangle(Latitude centerLatitude,
                                          Longitude centerLongitude,
                                          Angle halfWidth)

Sets that latitude and longitude ranges for this filter. Calling this method is equivalent to calling:

   setLatitude(centerLatitude, halfWidth);
   setLongitude(centerLongitude, halfWidth);
 

Parameters:

centerLatitude - the central value of the latitude range.

centerLongitude - the central value of the longitude range.

halfWidth - half the width of both the latitude and longitude ranges.

setLongitude

public void setLongitude(Longitude center,
                         Angle halfWidth)

Sets the longitude range for this filter. The range is from center minus halfWidth through center plus halfWidth.

Parameters:

center - the central point of the range.

halfWidth - half the width of the range.

setLongitudeRange

public void setLongitudeRange(Longitude from,
                              Longitude to)

Sets the longitude range for this filter. Note that the from value is allowed to be numerically larger than the to value. This would be the case, for example, if you wanted to select positions whose longitudes where in the range 355 to 10 degrees.

Parameters:

from - the start of the range of longitude values that are allowed to pass through this filter. If this value is null or ANY_LONGITUDE, a longitude of zero will be used.

to - the end of the range of longitude values that are allowed to pass through this filter. If this value is null or ANY_LONGITUDE, a longitude whose value is equal to a full circle will be used.

setLongitudeRange

public void setLongitudeRange(LongitudeInterval newInterval)

Sets the longitude range for this filter.

Parameters:

newInterval - the new range.

setLatitude

public void setLatitude(Latitude center,
                        Angle halfWidth)

Sets the latitude range for this filter. The range is from center minus halfWidth through center plus halfWidth.

Parameters:

center - the central point of the range.

halfWidth - half the width of the range.

setLatitudeRange

public void setLatitudeRange(Latitude min,
                             Latitude max)

Sets the latitude range for this filter. To specify an unbounded minimum and/or maximum, use the constant ANY_LATITUDE.

Parameters:

min - the minimum latitude that is allowed to pass through this filter.

max - the maximum latitude that is allowed to pass through this filter.

setDistance

public void setDistance(Distance center,
                        Distance halfWidth)

Sets the distance range for this filter. The range is from center minus halfWidth through center plus halfWidth.

Parameters:

center - the central point of the range.

halfWidth - half the width of the range.

setDistanceRange

public void setDistanceRange(Distance min,
                             Distance max)

Sets the distance range for this filter. To specify an unbounded minimum and/or maximum, use the constant ANY_DISTANCE.

Parameters:

min - the minimum distance that is allowed to pass through this filter.

max - the maximum distance that is allowed to pass through this filter.

setQueryTime

public void setQueryTime(Date time)

Sets the date and time at which the filtered position is queried for its longitude, latitude, and distance.

Parameters:

time - the time used by the allows(SkyPosition) and blocks(SkyPosition) methods when querying a position.

blocks

public boolean blocks(SkyPosition sp)

Returns true if this filter blocks the given position. Null positions are always blocked.

Specified by:

blocks in interface Filter<SkyPosition>

Parameters:

sp - the position to be filtered.

Returns:

true if this filter blocks sp.

allows

public boolean allows(SkyPosition sp)

Returns true if this filter allows the given position to pass through it. Null positions are always blocked.

Specified by:

allows in interface Filter<SkyPosition>

Parameters:

sp - the position to be filtered.

Returns:

true if this filter allows sp to pass through it.

removeAllBlockedParticlesFrom

public Collection<? extends SkyPosition> removeAllBlockedParticlesFrom(Collection<? extends SkyPosition> flow)

Removes from flow any position that is blocked by this filter.

Parameters:

flow - a collection of positions that this filter will alter by removing blocked positions.

Returns:

flow, after the removal of blocked positions. If flow is null, a new empty collection is returned.