d3
=================

*WARNING: this package is still in dev. expect bugs*

d3 is another popular DOM manipulation library available in javascript. This is the python port of that.

It has several utilities for working with the DOM.

selection
----------------

d3's selection API is very powerful.

.. code-block :: python

	from domonic.dom import *
	from domonic.html import *
	from domonic.d3.selection import *

	import domonic.d3 as d3


format
----------------

d3's has a library for formatting numbers to avoid things like floating precision

.. code-block :: python

	from domonic.dom import *
	from domonic.html import *
	from domonic.d3.format import *
	from domonic.d3.format import format


dispatch
----------------

d3 has an event system

.. code-block :: python

	from domonic.dom import *
	from domonic.html import *
	from domonic.d3.dispatch import dispatch, Dispatch


path
----------------

d3's path API converts SVG paths to a d3.path object which is compatible with canvas.

.. code-block :: python

	from domonic.svg import *
	from domonic.d3.path import Path


polygon
----------------

d3's has shape API

.. code-block :: python

	from domonic.d3.polygon import *

D3 expects a "polygon" is a 2D array of integers listed counterclockwise (clockwise works too). 
This does not work with the polygon as defined by SVG, SVG polygons have a points method you can parse into a 2D array and use here.

polygonArea() finds the area of a given polygon. It returns a float/int.

.. code-block :: python

    def test_polygonArea(self):
        irreg_0 = [[5,11],[12,4],[7,7],[6,1]]       # area: 15
        irreg_1 = [[-6,12],[23,2],[19,-8],[-7,-6]]  # area: 400
        irreg_2 = [[0,4],[12,8],[23,-5],[-5,-3]]    # area: 203
        square = [[0,4],[4,4],[4,0],[0,0]]          # area: 16
        triangle = [[-4,0],[0,4],[2,0]]             # area: 12

        self.assertEqual(polygonArea(irreg_0), 15)
        self.assertEqual(polygonArea(irreg_1), 400)
        self.assertEqual(polygonArea(irreg_2), 203)
        self.assertEqual(polygonArea(square), 16)
        self.assertEqual(polygonArea(triangle), 12)

polygonCentroid() finds the center of mass of a given polygon. It returns 2 ints in an array, representing the point of the polygons center of mass.

.. code-block :: python

    def test_polygonCentroid(self): 
        irreg = [[-4,0],[8,12],[4,8],[-4,-4],[0,0]] # centroid: [0, 4]
        square = [[0,4],[4,4],[4,0],[0,0]]          # centroid: [2, 2]
        triangle = [[-4,0],[0,4],[4,2]]             # centroid: [0, 2]

        self.assertEqual(polygonCentroid(irreg), [0, 4])
        self.assertEqual(polygonCentroid(square), [2, 2])
        self.assertEqual(polygonCentroid(triangle), [0, 2])

polygonHull() takes a 2D array of points and determines the polygon hull using andrew's monotone chain algorithm. It returns the polygon hull as a 2D array of points.

.. code-block :: python

    def test_polygonHull(self):
        points_0 = [[0,6],[12,8],[23,-5],[-5,-3],[5,11],[12,4],[7,7],[6,1]]
        points_1 = [[-4,0],[8,12],[4,8],[-4,-4],[0,0],[-6,12],[23,2],[19,-8],[-7,-6]]

        hull_0 = [[-5,-3],[0,6],[5,11],[12,8],[23,-5]]
        hull_1 = [[-7,-6],[-6,12],[8,12],[19,-8],[23,2]]
        
        self.assertEqual(polygonHull(points_0), hull_0)
        self.assertEqual(polygonHull(points_1), hull_1)

polygonContains() takes a polygon and a point, it returns true if the point is inside the polygon, false otherwise.

.. code-block :: python

    def test_polygonContains(self):
        irreg_0 = [[5,11],[12,4],[7,7],[6,1]]
        square = [[0,4],[4,4],[4,0],[0,0]]
        triangle = [[-4,0],[0,4],[2,0]]

        self.assertTrue(polygonContains(irreg_0, [6,8]))
        self.assertFalse(polygonContains(irreg_0, [0,0]))
        self.assertTrue(polygonContains(square, [2,2]))
        self.assertFalse(polygonContains(square, [-2,-2]))
        self.assertTrue(polygonContains(triangle, [0,1]))
        self.assertFalse(polygonContains(triangle, [0,-1]))

polygonLength() takes a polygon and returns the sum of the length of the polygon's sides.

.. code-block :: python

    def test_polygonLength(self):
        irreg_0 = [[5,11],[12,4],[7,7],[6,1]]   # length = 31.863
        square = [[0,4],[4,4],[4,0],[0,0]]      # length = 16
        triangle = [[-4,0],[0,4],[2,0]]         # length ~ 16.129

        self.assertEqual(round(polygonLength(irreg_0), 3), 31.863)
        self.assertEqual(polygonLength(square), 16)
        self.assertEqual(round(polygonLength(triangle), 3), 16.129)

.. automodule:: domonic.d3
    :members:
    :noindex: