Boxes and Polygons in ADQL/STC. Questions and recommendation.

Fri Oct 23 14:27:07 PDT 2009

Arnold Rots wrote:
> These shapes are based on their definitions in STC, so I would urge
> you not to change anything. The "box" you are referring to is a 2-D
> coordinate interval.
> 
>   - Arnold
>

Hi Arnold,

It looks like  the STC definition of a Polygon below is not consistent 
with the ADQL definition which begins (2.4.13) 'This function expresses 
a region on the sky with sides denoted by great circles passing through 
specified points.'  The STC version allows more than great circle 
boundaries.  So while an STC polygon can have small circle (parallels of 
latitude) sides, an ADQL polygon cannot.   The ADQL defintion of a box 
says that it is a special case of a polygon so, in ADQL a box cannot 
have small circle sides.

I'm not familiar enough with the STC documentation to understand if in 
the definition of Box there
   "The box’s sides are <line segments> or great circles  ..."
allows small circle sides to be used inside a box-- perhaps STC can 
treat such boundaries as 'line segments'.  Regardless ADQL polygons are 
apparently (if perhaps inadvertantly) more restrictive.

So I'm a little unclear from your answer whether an STC box is supposed
to represent a region
    minLon < alpha < maxLon , minLat < delta < maxLat
that I think of as a box, or a region with geodesic boundaries.  The 
complex procedure invoking the perpendiculars to the cross strongly 
suggested the later to me.

If the later I personally don't care whether we change it in ADQL, but I 
am curious as to where it is useful to have this construct and if there 
aren't any reasons to keep it, then maybe a coordinate range box would 
be more helpful to users.

By the by I'm glad to see from Pat's comment, that STC addresses the 
inside/outside issue.

	Tom

> FYI, from STC:
> 
> 4.5.1.4 Polygon
> A Polygon (2-dimensional) is an ordered list of one or more vertices. Its area is
> defined as that contained within (i.e., to the left of) the lines connecting
> neighboring (that is, in the ordered list) vertices. If the CoordFlavor is
> CARTESIAN, these lines are truly lines. The last vertex in the list connects back
> to the first.
> If the CoordFlavor is SPHERICAL, the lines are, by default, great-circles, unless
> the Vertex object contains a SmallCircle object; in that case the line connecting
> that vertex with its predecessor is a small-circle (parallel). The curvature of the
> parallel is determined by the pole of the SpatialFrame in the current
> AstroCoordSystem, unless a PolePosition is explicitly specified in the Vertex
> object. It is the responsibility of the server to ensure that the positions of the two
> sequential vertices actually lie on a parallel that is consistent with the implied or
> specified pole. In order to avoid ambiguities in direction, vertices need to be less
> than 180° apart in both coordinates. Great circles or small circles spanning 180°
> require specification of an extra intermediate vertex.
> The area A of a polygon with n vertices x in Cartesian space may be calculated
> as:
>   [go to the document for the equation]
> The summation is over determinants of matrices formed by the position vectors xi
> of successive vertices; xn+1 = x1. In spherical space (left-handed coordinates) the
> area is:
>   [go to the document for the equation]
> are the polygon’s angles at the vertices. Reverse the sign for right-handed
> coordinates. If the coordinate system is defined on the surface of a body (rather
> than the celestial or unit sphere), one should multiply by the square of the radius.
> The boundaries are considered part of the region. The inside of the region is
> defined as that part of coordinate space that is encircled by the polygon in a
> counter-clockwise sense. What this means is that, in a plane, if A > 0, the “inside”
> of the polygon is included; if A < 0, the “outside” is selected. On a sphere with a
> left-handed (celestial) coordinate system, if A > 0, one has identified the inside of
> the polygon; if A < 0, one used the “outside” angles of the polygon and the area
> is really 4π − A . Note that the negation operation is a simple matter of reversing
> the order of the vertex list.
> 
> 4.5.1.5 Box
> A Box is a special case of a Polygon, defined purely for convenience. It is
> specified by a center position and size (in both coordinates) defining a cross
> centered on the center position and with arms extending, parallel to the
> coordinate axes at the center position, for half the respective sizes on either side.
> The box’s sides are line segments or great circles intersecting the arms of the
> cross in its end points at right angles with the arms.
> 
> Alex Szalay wrote:
>> I think Tom raises a good point, and since this will lead to a lot 
>> of confusion in the future, I think we might want to use BOX indeed 
>> in the (lat, lon) constraint sense, if others agree as well. We 
>> can always use a polygon for great circle boundaries. This is probably
>> the last moment when we can still change things since the implementations
>> are at an early stage.
>>
>>
>> --Alex
>>
>> -----Original Message-----
>> From: Tom McGlynn [mailto:Thomas.A.McGlynn at nasa.gov] 
>> Sent: Friday, October 23, 2009 2:25 PM
>> To: adql at ivoa.net; dal at ivoa.net
>> Subject: Boxes and Polygons in ADQL/STC. Questions and recommendation.
>>
>> In trying to implement the geometry elements of ADQL, I was a bit 
>> surprised when I finally read the definition of Box carefully.  I had 
>> assumed that it corresponded to a range in both coordinates.   That's 
>> what the PgSphere Box is.   However an ADQL box is a polygon, so it's
>> sides are all great circles.  If I've read this and done my geometry 
>> properly then, e.g.,  an ADQL box with a size of 180 degrees on both 
>> sides is in fact the hemisphere centered on the center of the box, i.e., 
>> a box and a circle are the same for that radius.  The area of the box is 
>> independent of the center of the box and depends only on the width fields.
>>
>> For small boxes, where spherical distortions and projections can be 
>> ignored, this definition of  a box might be a reasonable approximation 
>> to the field of view of an observation.  Still, since an ADQL box must 
>> be aligned with the coordinate axes, it's not really general enough for 
>> that kind of use.  It needs a positional angle or some such.  I guess 
>> one might hack the coordinate system element to address this, but I 
>> don't think that's appropriate.
>>
>> So my question is: What is a box intended to be used for?
>>
>> My comment is that I think it would be good if and when the ADQL 
>> document is revised to explicitly note that a box does not correspond to 
>>   a set of ranges in the coordinates since I suspect that others may, as 
>> I did, assume that meaning.
>>
>> 	Tom McGlynn
>>
>> P.S., If I may be permitted a second question. Given that a box is 
>> special case of polygon, then can I transform from one to the other?
>> E.g., given a box at (a,b) with widths (c,d), what are the coordinates
>> of the corners of the box.
>>
>> P.P.S.,  This points out an ambiguity in the definition of polygons in 
>> ADQL.  The definition requires only the vertices of the polygon, to 
>> create a boundary the divides the sphere into two regions.  However it 
>> doesn't say which of the two regions is 'inside'.  This is fairly clear
>> in the plane, where one region is always finite and the other always 
>> infinite.  For large regions on the sphere there is no such obvious way 
>> to distinguish regions.  E.g., consider the polygon:
>>
>>      POLYGON('ICRS GEOCENTER', 0,0,  120,0, 240,0)
>>
>> This is a 'triangle' consisting of three 120 degree segments of the 
>> equator.  Does it include the northern or southern hemisphere?
>>
>> I don't see any obvious resolution to this issue -- maybe allow a 
>> specification of a point that is inside the polygon?
>>
>>
> --------------------------------------------------------------------------
> Arnold H. Rots                                Chandra X-ray Science Center
> Smithsonian Astrophysical Observatory                tel:  +1 617 496 7701
> 60 Garden Street, MS 67                              fax:  +1 617 495 7356
> Cambridge, MA 02138                             arots at head.cfa.harvard.edu
> USA                                     http://hea-www.harvard.edu/~arots/
> --------------------------------------------------------------------------