source: trunk/docs/api/zoo-geometry-collection.txt @ 190

.. _api-zoo-geometry-collection:

ZOO.Geometry.Collection
=======================

A Collection is exactly what it sounds like: A collection of different Geometries.

Properties      
----------

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

   * - NAME
     - DESCRIPTION
   * - :ref:`components <components>`
     - {Array(ZOO.Geometry)} The component parts of this geometry
   * - :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.Collection <ZOO.Geometry.Collection>`
     - Creates a Geometry Collection -- a list of geoms.
   * - :ref:`destroy <destroy>`
     - Destroy this geometry.
   * - :ref:`clone <clone>`
     - Clone this geometry.
   * - :ref:`getComponentsString <getComponentsString>`
     - Get a string representing the components for this collection.
   * - :ref:`calculateBounds <calculateBounds>`
     - Recalculate the bounds by iterating through the components and calling extendBounds() on each item.
   * - :ref:`addComponent <addComponent>`
     - Add a new component (geometry) to the collection.
   * - :ref:`removeComponents <removeComponents>`
     - Remove components from this geometry.
   * - :ref:`removeComponent <removeComponent>`
     - Remove a component from this geometry.
   * - :ref:`getLength <getLength>`
     - Calculate the length of this geometry. 
   * - :ref:`getCentroid <getCentroid>`
     - {ZOO.Geometry.Point} The centroid of the collection.
   * - :ref:`getGeodesicLength <getGeodesicLength>`
     - Calculate the approximate length of the geometry were it projected onto the earth.
   * - :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:`equals <equals>`
     - Determine whether another geometry is equivalent to this one.
   * - :ref:`transform <transform>`
     - Reproject the components geometry from source to dest.
   * - :ref:`intersects <intersects>`
     - Determine if the input geometry intersects this one.
   * - :ref:`getVertices <getVertices>`
     - Return a list of all points in this geometry.      
   
     
**Properties**
       
.. _components: 

components      
  {Array(:ref:`ZOO.Geometry <api-zoo-geometry>`)} The component parts of this geometry
  
.. _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.Collection:

ZOO.Geometry.Collection 
  Creates a Geometry Collection -- a list of geoms.

  *Parameters*
  
  ``components`` {Array(:ref:`ZOO.Geometry <api-zoo-geometry>`)} Optional array of geometries 
  
.. _destroy: 
 
destroy 
  ::
  
    destroy: function ()

Destroy this geometry. 

.. _clone:   
  
clone   
  ::
  
    clone: function()

  Clone this geometry.
  
  *Returns*

  :ref:`{ZOO.Geometry.Collection} <api-zoo-geometry-collection>` An exact clone of this collection.
  
.. _getComponentsString:     
  
getComponentsString     
  ::
  
    getComponentsString: function()

  Get a string representing the components for this collection.
  
  *Returns*

  ``{String}`` A string representation of the components of this geometry.
  
.. _calculateBounds:  
  
calculateBounds 
  ::
  
    calculateBounds: function()

  Recalculate the bounds by iterating through the components and calling extendBounds() on each item.
  
.. _addComponent:    
  
addComponent    
  ::
  
    addComponent: function(component,index)

  Add a new component (geometry) to the collection.  If this.componentTypes is set, then the 
  component class name must be in the componentTypes array.  The bounds cache is reset.
  
  *Parameters*
  
  | ``component`` :ref:`{ZOO.Geometry} <api-zoo-geometry>` A geometry to add
  | ``index {int}`` Optional index into the array to insert the component
  
  *Returns*

  ``{Boolean}`` The component geometry was successfully added 
  
.. _removeComponents:      
  
removeComponents        
  ::
  
    removeComponents: function(components)

  Remove components from this geometry.\
  
  *Parameters*
  
  ``components`` {Array(:ref:`ZOO.Geometry <api-zoo-geometry>`)} The components to be removed  
  
.. _removeComponent:  
  
removeComponent 
  ::
  
    removeComponent: function(component)

  Remove a component from this geometry.
  
  *Parameters*
  
  ``component`` :ref:`{ZOO.Geometry} <api-zoo-geometry>`
  
.. _getLength:    
  
getLength       
  ::
  
    getLength: function()

  Calculate the length of this geometry
 
  *Returns*

  ``{Float}`` The length of the geometry  
  
.. _getCentroid:      
  
getCentroid     
  ::
  
    getCentroid: function()

  *Returns*

  :ref:`{ZOO.Geometry.Point} <api-zoo-geometry-point>` The centroid of the collection 
  
.. _getGeodesicLength:        
  
getGeodesicLength       
  ::
  
    getGeodesicLength: function(projection)

  Calculate the approximate length of the geometry were it projected onto the earth.

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

  ``{Float}`` The appoximate geodesic length of the geometry in meters. 
  
.. _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*
  
  :ref:`{ZOO.Geometry} <api-zoo-geometry>`  The current geometry.  

.. _equals:                
  
equals  
  ::
  
    equals: function(geometry)

  Determine whether another geometry is equivalent to this one.  Geometries are considered equivalent if 
  all components have the same coordinates.
  
  *Parameters*
  
  ``geom`` :ref:`{ZOO.Geometry} <api-zoo-geometry>` The geometry to test.

  *Returns*

  ``{Boolean}`` The supplied geometry is equivalent to this 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>`
  
.. _intersects:                    
  
intersects      
  ::
  
    intersects: function(geometry)

  Determine if the input geometry intersects this one.

  *Parameters*
  
  ``geometry`` :ref:`{ZOO.Geometry} <api-zoo-geometry>` Any type of geometry.

  *Returns*

  ``{Boolean}`` The input geometry intersects this one. 
  
.. _getVertices:                      
  
getVertices     
  ::
  
    getVertices: function(nodes)

  Return a list of all points in this geometry.
  
  *Parameters*
  
  ``nodes {Boolean}`` For lines, only return vertices that are endpoints.  If false, for lines, 
  only vertices that are not endpoints will be returned.  If not provided, all vertices will be returned.

  *Returns*

  ``{Array}`` A list of all vertices in the geometry.