# Face

Class representing a face (closed loop) in a `polygon` object. Face is a circular bidirectional linked list of `edges`. Face object cannot be instantiated with a constructor. Instead, use `polygon.addFace()` method.
Note, that face only set entry point to the linked list of edges but does not contain edges by itself. Container of edges is a property of the polygon object.

## Constructor

#### new Face()

Source:
  - classes/face.js, line 33

##### Example

    // Face implements "next" iterator which enables to iterate edges in for loop:
    for (let edge of face) {
         console.log(edge.shape.length)     // do something
    }

    // Instead, it is possible to iterate edges as linked list, starting from face.first:
    let edge = face.first;
    do {
      console.log(edge.shape.length);   // do something
      edge = edge.next;
    } while (edge != face.first)

### Classes

Face

### Members

#### _box

Reference to the last edge in face

Source:
  - classes/face.js, line 45

#### box

Return bounding box of the face

Source:
  - classes/face.js, line 158

#### edges

Return array of edges from first to last

Source:
  - classes/face.js, line 142

#### perimeter

Get all edges length

Source:
  - classes/face.js, line 173

#### shapes

Return array of shapes which comprise face

Source:
  - classes/face.js, line 150

### Methods

#### append(edge) → {Face}

Append edge after the last edge of the face (and before the first edge).

Source:
  - classes/face.js, line 221

##### Parameters:

Name | Type | Description
--- | --- | ---
`edge` | `Edge` | Edge to be appended to the linked list

##### Returns:

Type:
  `Face`

#### area() → {number}

Returns the absolute value of the area of the face

Source:
  - classes/face.js, line 343

##### Returns:

Type:
  `number`

#### findEdgeByPoint(pt) → {Edge}

Returns edge which contains given point

Source:
  - classes/face.js, line 458

##### Parameters:

Name | Type | Description
--- | --- | ---
`pt` | `Point` | test point

##### Returns:

Type:
  `Edge`

#### insert(newEdge, edgeBefore) → {Face}

Insert edge newEdge into the linked list after the edge edgeBefore

Source:
  - classes/face.js, line 236

##### Parameters:

Name | Type | Description
--- | --- | ---
`newEdge` | `Edge` | Edge to be inserted into linked list
`edgeBefore` | `Edge` | Edge to insert newEdge after it

##### Returns:

Type:
  `Face`

#### isSimple(edges) → {boolean}

Returns true if face of the polygon is simple (no self-intersection points found) NOTE: this method is incomplete because it does not exclude touching points. Self intersection test should check if polygon change orientation in the test point.

Source:
  - classes/face.js, line 394

##### Parameters:

Name | Type | Description
--- | --- | ---
`edges` | `PlanarSet` | reference to polygon edges to provide search index

##### Returns:

Type:
  `boolean`

#### merge_with_next_edge(edge) → {Face}

Merge current edge with the next edge. Given edge will be extended, next edge after it will be removed. The distortion of the polygon is on the responsibility of the user of this method

Source:
  - classes/face.js, line 263

##### Parameters:

Name | Type | Description
--- | --- | ---
`edge` | `Edge` | edge to be extended

##### Returns:

Type:
  `Face`

#### orientation() → {number}

Return face orientation: one of Flatten.ORIENTATION.CCW, Flatten.ORIENTATION.CW, Flatten.ORIENTATION.NOT_ORIENTABLE
According to Green theorem the area of a closed curve may be calculated as double integral, and the sign of the integral will be defined by the direction of the curve. When the integral ("signed area") will be negative, direction is counterclockwise, when positive - clockwise and when it is zero, polygon is not orientable. See https://mathinsight.org/greens_theorem_find_area

Source:
  - classes/face.js, line 373

##### Returns:

Type:
  `number`

#### pointAtLength(length) → {Point}

Get point on face boundary at given length

Source:
  - classes/face.js, line 182

##### Parameters:

Name | Type | Description
--- | --- | ---
`length` | `number` | The length along the face boundary

##### Returns:

Type:
  `Point`

#### remove(edge) → {Face}

Remove the given edge from the linked list of the face

Source:
  - classes/face.js, line 249

##### Parameters:

Name | Type | Description
--- | --- | ---
`edge` | `Edge` | Edge to be removed

##### Returns:

Type:
  `Face`

#### reverse()

Reverse orientation of the face: first edge become last and vice a verse, all edges starts and ends swapped, direction of arcs inverted. If face was oriented clockwise, it becomes counterclockwise and vice versa

Source:
  - classes/face.js, line 275

#### setArcLength()

Set arc_length property for each of the edges in the face. Arc_length of the edge it the arc length from the first edge of the face

Source:
  - classes/face.js, line 324

#### signedArea() → {number}

Returns signed area of the simple face. Face is simple if it has no self intersections that change its orientation. Then the area will be positive if the orientation of the face is clockwise, and negative if orientation is counterclockwise. It may be zero if polygon is degenerated.

Source:
  - classes/face.js, line 355

##### Returns:

Type:
  `number`

#### svg() → {string}

Returns string to be assigned to "d" attribute inside defined "path"

Source:
  - classes/face.js, line 485

##### Returns:

Type:
  `string`

#### toPolygon() → {Polygon}

Returns new polygon created from one face

Source:
  - classes/face.js, line 473

##### Returns:

Type:
  `Polygon`