diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/api.rst | 6 | ||||
| -rw-r--r-- | doc/source/conf.py | 10 | ||||
| -rw-r--r-- | doc/source/user.rst | 89 |
3 files changed, 100 insertions, 5 deletions
diff --git a/doc/source/api.rst b/doc/source/api.rst index c743c49..cdfea48 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -28,3 +28,9 @@ Graph operations on polygons .. automodule:: sphere.graph :members: + +Skylines +-------- + +.. automodule:: sphere.skyline + :members: diff --git a/doc/source/conf.py b/doc/source/conf.py index 5ee1814..94a92fb 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -44,16 +44,16 @@ master_doc = 'index' # General information about the project. project = u'Spherical Geometry Toolkit' -copyright = u'2011, Michael Droettboom, STScI' +copyright = u'2011-2012, Michael Droettboom and Pey Lian Lim, STScI' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.1' +version = '0.2' # The full version, including alpha/beta/rc tags. -release = '0.1' +release = '0.2' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -182,7 +182,7 @@ htmlhelp_basename = 'SphericalGeometryToolkitdoc' # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'SphericalGeometryToolkit.tex', u'Spherical Geometry Toolkit Documentation', - u'Michael Droettboom, STScI', 'manual'), + u'Michael Droettboom and Pey Lian Lim, STScI', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -215,7 +215,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'sphericalgeometrytoolkit', u'Spherical Geometry Toolkit Documentation', - [u'Michael Droettboom, STScI'], 1) + [u'Michael Droettboom and Pey Lian Lim, STScI'], 1) ] # If true, show URL addresses after external links. diff --git a/doc/source/user.rst b/doc/source/user.rst index e17db6f..60b77d8 100644 --- a/doc/source/user.rst +++ b/doc/source/user.rst @@ -13,6 +13,12 @@ Requirements - Numpy 1.4 or later +- PyFITS + +- PyWCS + +- STWCS + Coordinate representation ------------------------- @@ -135,6 +141,14 @@ operations available: - `~SphericalPolygon.overlap`: Determine how much a given polygon overlaps another. + - `~SphericalPolygon.to_radec`: Convert (*x*, *y*, *z*) points in the + polygon to (*ra*, *dec*) points. + + - `~SphericalPolygon.same_points_as`: Determines if one polygon has the + same points as another. When only sorted unique points are considered + (default behavior), polygons with same points might not be the same + polygons because the order of the points matter. + - `~SphericalPolygon.draw`: Plots the polygon using matplotlib’s Basemap toolkit. This feature is rather bare and intended primarily for debugging purposes. @@ -158,3 +172,78 @@ functions that are useful for dealing with them. - `angle`: Calculate the angle between two great circle arcs. - `midpoint`: Calculate the midpoint along a great circle arc. + +Skylines +-------- + +Skylines are designed to capture and manipulate HST WCS image information as +spherical polygons. They are represented by the `~sphere.skyline.SkyLine` class, +which is an extension of `~sphere.polygon.SphericalPolygon` class. + +Representation +`````````````` +Each skyline has a list of members, `~sphere.skyline.SkyLine.members`, and a +composite spherical polygon, `~sphere.skyline.SkyLine.polygon`, defined by those +members. The polygon has all the functionalities of +`~sphere.polygon.SphericalPolygon`. + +What is a skyline member? +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each member in `~sphere.skyline.SkyLine.members` belongs to the +`~sphere.skyline.SkyLineMember` class, which contains image name (with path if +given), science extension, and WCS object and polygon of that extension. + +For example, an ACS/WFC full-frame image would give 2 members, one from EXT 1 +and another from EXT 4. + +Creating skylines +````````````````` + +`~sphere.skyline.SkyLine` constructor takes an image name and an optional +`extname` keyword, which defaults to "SCI". To create skyline from +single-extension FITS, change `extname` to "PRIMARY". + +If `None` is given instead of image name, an empty skyline is created with no +member and an empty spherical polygon. + +Operations on skylines +`````````````````````` + +`~sphere.skyline.SkyLine` has direct access to most of the +`~sphere.polygon.SphericalPolygon` properties and methods *except* for the +following (which are still accessible indirectly via +`~sphere.skyline.SkyLine.polygon`): + + - `~sphere.polygon.SphericalPolygon.from_radec` + - `~sphere.polygon.SphericalPolygon.from_cone` + - `~sphere.polygon.SphericalPolygon.from_wcs` + - `~sphere.polygon.SphericalPolygon.multi_union` + - `~sphere.polygon.SphericalPolygon.multi_intersection` + +In addition, `~sphere.skyline.SkyLine` also has these operations available: + + - `~sphere.skyline.SkyLine.to_wcs`: Return a composite HST WCS object defined + by all the members. + + - `~sphere.skyline.SkyLine.add_image`: Return a new skyline that is the union + of two skylines. This should be used, *not* `SkyLine.union` (which is + actually `~sphere.polygon.SphericalPolygon.union`) that will not include + members. + + - `~sphere.skyline.SkyLine.find_intersection`: Return a new skyline that is + the intersection of two skylines. This should be used, *not* + `SkyLine.intersection` (which is actually + `~sphere.polygon.SphericalPolygon.intersection`) that will not include + members. + + - `~sphere.skyline.SkyLine.find_max_overlap` and + `~sphere.skyline.SkyLine.max_overlap_pair`: Return a pair of skylines that + overlap the most from a given list of skylines. + + - `~sphere.skyline.SkyLine.mosaic`: Return a new skyline that is a mosaic of + given skylines that overlap, a list of image names of the skylines used, and + a list of image names of the excluded skylines. A pair of skylines with the + most overlap is used as a starting point. Then a skyline that overlaps the + most with the mosaic is used, and so forth until no overlapping skyline is + found. |