(r1) ADQLGeomFuncSemantics < IVOA

IVOA Web>IvoaVOQL>ADQLv2RFC>ADQLGeomFuncSemantics (revision 1) (raw view)~~EditAttach~~
---+ Recommended Edits to ADQL V2.0 PR: Geometric Function Semantics

This document provides suggested edits that addresses Ray Plante's RFC Comment that called for more explicit enumeration of the types and meanings associated with geometrical functions.

In general, the aim of these suggestions is provide a crisp definition of each function at the beginning of the section.  In many of the function descriptions currently, the type and meaning are given by example, which is not a good practice and can lead to ambiguities.  In contrast, unambiguous statements up front will make the document a better reference for implementers, particularly when "looking up" a specific function.  

Note that *bold* within the suggested text below indicate new or changed words.  

---+++ 2.4.2. AREA

Change the first sentence to:

<blockquote>
This function computes the area, in square degrees, of *the region given by the function's only argument*.
</blockquote>

Prepend the 2nd paragraph with the line:

<blockquote>
*The argument can be represented with one of the region functions, BOX, CIRCLE, POLYGON, or REGION.*
</blockquote>

---+++ 2.4.3 BOX

Change 2nd sentence to 

<blockquote>
A box is a special case of Polygon, defined purely for convenience, *and it corresponds in meaning to the STC-S "Box" subphrase [4].*  
</blockquote>

The second paragraph sufficiently describes the arguments.  

---+++ 2.4.4 CENTROID

Change the first paragraph to:

<blockquote>
This function computes the centroid of *the region given by the function's only argument* and returns a POINT (See 2.4.11).
</blockquote>

Prepend the 2nd paragraph with the line:

<blockquote>
*The argument can be represented with one of the region functions, BOX, CIRCLE, POLYGON, or REGION.*
</blockquote>


---+++ 2.4.5.  CIRCLE

Change the first paragraph's first sentence to:

<blockquote>
This function expresses a circular region on the sky (a cone in space) *and corresponds in meaning to the "Circle" STC-S subphrase [4].  
</blockquote>

The reset of paragraph sufficiently describes the arguments.  

---+++ 2.4.6  CONTAINS

The return type is given in the 2nd paragraph after the first example, and arguments are defined in the last paragraph after the examples.  It would be better to put a crisper definition up front.  

Append to the first paragraph:

<blockquote>
*The first argument is a point or region value representing the contained geometry, and the second argument is a region value representing the containing region.  The function returns 1 (meaning true) if the contained geometry is entirely within the boundary of the containing region and 0 (meaning false) otherwise.  When the first argument is a point, it is considered inside the containing region if it lies on the containing region's border.*
</blockquote>

Using the following text, move the contents of the last paragraph to a new paragraph after the first one:

<blockquote>
*Either argument can be given by the appropriate functions (the region functions--BOX, CIRCLE, POLYGON, or REGION--for the second argument, and the region functions or POINT for the first argument) or by a single column name or alias.  When a column name or alias is provided, the value in the column or alias must be interpreted the appropriate value type.  Since the two argument geometries may be expressed in different coordinate systems, the function is responsible for converting one (or both).  If either argument cannot be converted to the proper geometry in a usable coordinate system, the function should throw an error message (as defined by the service making use of ADQL).* 
</blockquote>

Drop the last paragraph.  

---+++ 2.4.7 COORD1

<blockquote>
This function returns the first coordinate value, in degrees, of a position given *by the first argument.  The argument may be given using the* POINT function (See 2.4.12) or *a* column reference. 
</blockquote>


---+++ 2.4.8 COORD2

<blockquote>
This function returns the second coordinate value, in degrees, of a position given *by the first argument.  The argument may be given using the* POINT function (See 2.4.12) or *a* column reference. 
</blockquote>

---+++ 2.4.12 POINT

This is sufficiently explicit.

---+++ 2.4.13 POLYGON

Insert the following into the second paragraph as the second sentence:

<blockquote>
*This function corresponds in meaning to the "Polygon" STC-S sub-phrase  [4].*
</blockquote>

The explanation of the arguments is sufficient.

---+++ 2.4.14 REGION

This is sufficiently described.


<br/>
<!--
      * Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
-->
Topic revision: r1 - 2008-10-22 - RayPlante
IVOA
Log in or Register
IVOA.net
Wiki Home
WebChanges
WebTopicList
WebStatistics
Twiki Meta & Help
IVOA
Know
Main
Sandbox
TWiki
TWiki intro
TWiki tutorial
User registration
Notify me
Working Groups
Interest Groups
Committees
Stds&Procs
www.ivoa.net
Documents
Events
Members
XML Schema