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

.. _api-zoo-geometry-collection:

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

A Collection is exactly what it sounds like: A collection of different Geometries.  
These are stored in the local parameter :ref:`components <components>` (which can 
be passed as a parameter to the constructor).

As new geometries are added to the collection, they are NOT cloned.  When removing geometries, 
they need to be specified by reference (ie you have to pass in the exact geometry to be removed).

The <getArea> and :ref:`getLength <getLength>` functions here merely iterate through the components, 
summing their respective areas and lengths.

Create a new instance with the :ref:`ZOO.Geometry.Collection <ZOO.Geometry.Collection>` constructor.

Inherits from

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

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.