source: branches/branch-1.6/docs/api/zoo-geometry-linearring.txt @ 809

.. _api-zoo-geometry-linearring:

ZOO.Geometry.LinearRing
=======================

A Linear Ring is a special LineString which is closed.  It closes itself automatically 
on every addPoint/removePoint by adding a copy of the first point as the last point.

Also, as it is the first in the line family to close itself, a getArea() function is 
defined to calculate the enclosed area of the linearRing

Inherits from

- :ref:`ZOO.Geometry.LineString <api-zoo-geometry-linestring>`

Properties      
----------

.. list-table::
   :widths: 12 50
   :header-rows: 1

   * - NAME
     - DESCRIPTION
   * - :ref:`componentTypes <componentTypes>`
     - {Array(String)} An array of class names representing the types of components that the collection can include.

Functions       
---------

.. list-table::
   :widths: 15 50
   :header-rows: 1

   * - NAME
     - DESCRIPTION   
   * - :ref:`ZOO.Geometry.LinearRing <ZOO.Geometry.LinearRing>`
     - Linear rings are constructed with an array of points.
   * - :ref:`addComponent <addComponent>`
     - Adds a point to geometry components.  
   * - :ref:`move <move>`
     - Moves a geometry by the given displacement along positive x and y axes.
   * - :ref:`rotate <rotate>`
     - Rotate a geometry around some origin   
   * - :ref:`resize <resize>`
     - Resize a geometry relative to some origin.
   * - :ref:`transform <transform>`
     - Reproject the components geometry from source to dest. 
   * - :ref:`getCentroid <getCentroid>`
     - {ZOO.Geometry.Point} The centroid of the ring
   * - :ref:`getArea <getArea>`
     -     
   * - :ref:`getGeodesicArea <getGeodesicArea>`
     - Calculate the approximate area of the polygon were it projected onto the earth.   
   * - :ref:`containsPoint <containsPoint>`
     - Test if a point is inside a linear ring.     
     
**Properties**
       
.. _componentTypes: 

componentTypes  
  ``{Array(String)}`` An array of class names representing the types of components that the 
  collection can include.  A null value means the component types are not restricted.  
  
**Functions** 

.. _ZOO.Geometry.LinearRing: 

ZOO.Geometry.LinearRing 
  Linear rings are constructed with an array of points.  This array can represent a closed 
  or open ring.  If the ring is open (the last point does not equal the first point), 
  the constructor will close the ring.  If the ring is already closed (the last point does 
  equal the first point), it will be left closed.
  
  *Parameters*
  
  ``points`` {Array(:ref:`ZOO.Geometry.Point <api-zoo-geometry-point>`)} points  
  
.. _addComponent:   
  
addComponent    
  ::
  
    addComponent: function(point,index)

  Adds a point to geometry components.  If the point is to be added to the end of the 
  components array and it is the same as the last point already in that array, the 
  duplicate point is not added.  This has the effect of closing the ring if it is not 
  already closed, and doing the right thing if it is already closed.  This behavior can be 
  overridden by calling the method with a non-null index as the second argument.
  
  *Parameter*
  
  | ``point`` :ref:`{ZOO.Geometry.Point} <api-zoo-geometry-point>`
  | ``index {Integer}`` Index into the array to insert the component

  *Returns*

  ``{Boolean}`` Was the Point successfully added?  
  
.. _move:     
  
move    
  ::
  
    move: function(x,y)

  Moves a geometry by the given displacement along positive x and y axes.  This 
  modifies the position of the geometry and clears the cached bounds.
  
  *Parameters*
  
  | ``x {Float}`` Distance to move geometry in positive x direction.
  | ``y {Float}`` Distance to move geometry in positive y direction.  

.. _rotate:       
  
rotate  
  ::
  
    rotate: function(angle,origin)

  Rotate a geometry around some origin

  *Parameters*
  
  | ``angle {Float}`` Rotation angle in degrees (measured counterclockwise from the positive x-axis)
  | ``origin`` :ref:`{ZOO.Geometry.Point} <api-zoo-geometry-point>` Center point for the rotation  

.. _resize:         
  
resize  
  ::
  
    resize: function(scale,origin,ratio)

  Resize a geometry relative to some origin.  Use this method to apply a uniform scaling to a geometry.

  *Parameters*
  
  | ``scale {Float}`` Factor by which to scale the geometry.  A scale of 2 doubles the size of the geometry in each dimension (lines, for example, will be twice as long, and polygons will have four times the area).
  | ``origin`` :ref:`{ZOO.Geometry.Point} <api-zoo-geometry-point>` Point of origin for resizing
  | ``ratio {Float}`` Optional x:y ratio for resizing.  Default ratio is 1.

  *Returns*
  
  ``{ZOO.Geometry}`` The current geometry.
  
.. _transform:           
  
transform       
  ::
  
    transform: function(source,dest)

  Reproject the components geometry from source to dest.

  *Parameters*
  
  | ``source`` :ref:`{ZOO.Projection} <api-zoo-projection>`
  | ``dest`` :ref:`{ZOO.Projection} <api-zoo-projection>`

  *Returns*

  :ref:`{ZOO.Geometry} <api-zoo-geometry>` 
  
.. _getCentroid:             
  
getCentroid     
  ::
  
    getCentroid: function()

  *Returns*

  :ref:`{ZOO.Geometry.Point} <api-zoo-geometry-point>` The centroid of the ring  

.. _getArea:               
  
getArea 
  ::
  
    getArea: function()

  .. note:: The area is positive if the ring is oriented CW, otherwise it will be negative.

  *Returns*

  ``{Float}`` The signed area for a ring.

.. _getGeodesicArea:               

getGeodesicArea 
  ::
  
    getGeodesicArea: function(projection)

  Calculate the approximate area of the polygon were it projected onto the earth.  Note that 
  this area will be positive if ring is oriented clockwise, otherwise it will be negative.

  *Parameters*
  
  ``projection`` :ref:`{ZOO.Projection} <api-zoo-projection>` The spatial reference system for the geometry coordinates.  If not provided, Geographic/WGS84 is assumed.

  *Reference*

  Robert.  G. Chamberlain and William H.  Duquette, "Some Algorithms for Polygons on a Sphere", 
  JPL Publication 07-03, Jet Propulsion Laboratory, Pasadena, CA, June 2007 http://trs-new.jpl.nasa.gov/dspace/handle/2014/40409

  *Returns*

  ``{float}`` The approximate signed geodesic area of the polygon in square meters.  

.. _containsPoint:                 
  
containsPoint   
  ::
  
    containsPoint: function(point)

  Test if a point is inside a linear ring.  For the case where a point is coincident with a 
  linear ring edge, returns 1.  Otherwise, returns boolean.

  *Parameters*

  ``point`` :ref:`{ZOO.Geometry.Point} <api-zoo-geometry-point>`

  *Returns*

  ``{Boolean | Number}`` The point is inside the linear ring.  Returns 1 if the point is coincident with an edge.  Returns boolean otherwise.