=============================
Primitives (hwx.inspire.core)
=============================

Utilites to create parts with primitive shapes.

The supported primitive shapes are block, cone, polygon, ellipsoid,
prism, sphere, torus and etc.

--------------
Public Methods
--------------

  +--------------------------------------------------------------------------------+
  | createCurves_ (self, points, **kwds)                                           |
  +--------------------------------------------------------------------------------+
  | createEmptyPart_ (self, **kwds)                                                |
  +--------------------------------------------------------------------------------+
  | createPointPart_ (self, **kwds)                                                |
  +--------------------------------------------------------------------------------+
  | createPolylines_ (self, points, **kwds)                                        |
  +--------------------------------------------------------------------------------+
  | createSheetCircle_ (self, radius=1, **kwds)                                    |
  +--------------------------------------------------------------------------------+
  | createSheetPolygon_ (self, radius=1, nsides=3, **kwds)                         |
  +--------------------------------------------------------------------------------+
  | createSheetRectangle_ (self, x=1, y=1, **kwds)                                 |
  +--------------------------------------------------------------------------------+
  | createSolidBlock_ (self, x=1, y=1, z=1, **kwds)                                |
  +--------------------------------------------------------------------------------+
  | createSolidCone_ (self, radius=1, height=1, semiangle=0, **kwds)               |
  +--------------------------------------------------------------------------------+
  | createSolidCylinder_ (self, radius=1, height=1, **kwds)                        |
  +--------------------------------------------------------------------------------+
  | createSolidEllipsoid_ (self, xRadius=1, yRadius=0.5, zRadius=0.25, **kwds)     |
  +--------------------------------------------------------------------------------+
  | createSolidPrism_ (self, radius=1, height=1, nsides=20, blendradius=0, **kwds) |
  +--------------------------------------------------------------------------------+
  | createSolidSphere_ (self, radius=1, **kwds)                                    |
  +--------------------------------------------------------------------------------+
  | createSolidTorus_ (self, majorRadius=1, minorRadius=0.5, **kwds)               |
  +--------------------------------------------------------------------------------+

--------------
Method Details
--------------

.. _createCurves:
.. method:: createCurves(self, points, **kwds)

Creates and returns a list of parts containing curve connecting the points.

If curve doesn't self-intersect, will return a curve part.

If line does self-intersect, will return a curve part for each section.

:param points: list of points to create curve.
:type points: list[Point],list[tuple],list[list]
:param \*\*kwds: Part properties like material, color, name...

:returns: Created curve part.
:rtype: list [Part]


.. _createEmptyPart:
.. method:: createEmptyPart(self, **kwds)

Creates an empty part.

:param \*\*kwds: To set part properties like material, color, mass, name ...

:returns: Created empty part.
:rtype: Part


.. _createPointPart:
.. method:: createPointPart(self, **kwds)

Creates and returns a point part with a vertex feature.

Used to create a concentrated mass.

:param \*\*kwds: Part properties like material, color, name ...

:returns: Created point part.
:rtype: Part


.. _createPolylines:
.. method:: createPolylines(self, points, **kwds)

Creates and returns a list of parts containing line that connects the points.

If the line doesn't self-intersect, will returns a polyline part.

If the line does self-intersect, will contain a line part for each section.

:param points: List of points to create line.
:type points: list[Point], list[tuple], list[list]
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created poly lines.
:rtype: list[Part]


.. _createSheetCircle:
.. method:: createSheetCircle(self, radius=1, **kwds)

Create a new part containing a circle with centre at the origin in the
xy plane.

:param radius: Size in xy plane. Must be > 0.
:type radius: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created sheet part.
:rtype: Part


.. _createSheetPolygon:
.. method:: createSheetPolygon(self, radius=1, nsides=3, **kwds)

Create a new part containing a regular polygon with centre at the origin
in the XY plane.

:param radius: Size in xy plane. Must be > 0.
:type radius: int, float
:param nsides: Number of sides. Must be > 2.
:type nsides: int
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created sheet polygon part.
:rtype: Part


.. _createSheetRectangle:
.. method:: createSheetRectangle(self, x=1, y=1, **kwds)

Create a new part containing a rectangle with centre at the origin.

:param x: Size in x.  Must be > 0.
:type x: int, float
:param y: Size in y.  Must be > 0.
:type y: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created sheet rectangle part.
:rtype: Part


.. _createSolidBlock:
.. method:: createSolidBlock(self, x=1, y=1, z=1, **kwds)

Creates a new part containing a solid block with centre of the base at
origin.

:param x: Provide length.
:type x: int,float
:param y: Provide width.
:type y: int,float
:param z: Provide depth.
:type z: int, float
:param \*\*kwds: Part properties like material, color, name...

:returns: Created solid block.
:rtype: Part


.. _createSolidCone:
.. method:: createSolidCone(self, radius=1, height=1, semiangle=0, **kwds)

Create a new part containing a solid cone with centre of the base at
origin.

:param radius: Radius in xy plane. Must be > 0.
:type radius: int, float
:param height: Height in +z direction. Must be > 0.
:type height: int, float
:param semiangle: Semiangle in +z axis. Must be > 0 < pi/2.
:type semiangle: float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created solid cone.
:rtype: Part


.. _createSolidCylinder:
.. method:: createSolidCylinder(self, radius=1, height=1, **kwds)

Create a new part containing a solid cylinder with centre of the base at
origin.

:param radius: Radius to cylinder. Radius in the xy plane.
            Must be > 0.
:type radius: int,float
:param height: Height to cylinder. Height in the +z direction.
            Must be > 0.
:type height: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created solid cylinder.
:rtype: Part


.. _createSolidEllipsoid:
.. method:: createSolidEllipsoid(self, xRadius=1, yRadius=0.5, zRadius=0.25, **kwds)

Create a new part containing a solid ellipsoid with centre at the origin.

:param xRadius: Size in x direction. Must be > 0.
:type xRadius: int, float
:param yRadius: Size in y direction. Must be > 0.
:type yRadius: int, float
:param zRadius: Size in z direction. Must be > 0.
:type zRadius: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created solid ellipsoid.
:rtype: Part


.. _createSolidPrism:
.. method:: createSolidPrism(self, radius=1, height=1, nsides=20, blendradius=0, **kwds)

Create a new part containing a solid prism with centre of the base at origin.

:param radius: Radius to solid prism in the xy plane. Must be > 0.
:type radius: int, float
:param height: Height to solid prism in the +z direction.
:type height: int, float
:param nsides: Number of facets. Must be > 2.
:type nsides: int
:param blendradius: Radius to round the corners.
:type blendradius: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created solid prism.
:rtype: Part


.. _createSolidSphere:
.. method:: createSolidSphere(self, radius=1, **kwds)

Create a new part containing a solid sphere with
centre at origin.

:param radius: Radius in the xy plane. Must be > 0.
:type radius: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created solid sphere.
:rtype: Part


.. _createSolidTorus:
.. method:: createSolidTorus(self, majorRadius=1, minorRadius=0.5, **kwds)

Create a new part containing a solid torus with centre at the origin.

:param majorRadius: Size in xy. Must be > 0.
:type majorRadius: int, float
:param minorRadius: Size in z. Must be < majorRadius.
:type minorRadius: int, float
:param \*\*kwds: Part properties like material, color, name ...

:returns: Created solid torus.
:rtype: Part