# Class: Agentmap

## Agentmap(map, animation_intervalopt)

#### new Agentmap(map, animation_intervalopt)

The main class for building, storing, simulating, and manipulating agent-based models on Leaflet maps.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`map` | object |  |  | A Leaflet Map instance.
`animation_interval` | number | <optional> | 1 | The number of steps agents must move before being redrawn. Given 1, they will be redrawn after every step. Given 0, the animation will not update at all. 1 by default. Must be a nonnegative integer.

##### Properties:

Name | Type | Attributes | Description
--- | --- | --- | ---
`map` | object |  | A Leaflet Map instance.
`agents` | FeatureGroup |  | A featureGroup containing all agents.
`units` | FeatureGroup |  | A featureGroup containing all units.
`streets` | FeatureGroup |  | A featureGroup containing all streets.
`state` | object |  | Properties detailing the state of the simulation process. ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`running` | boolean |  | Whether the simulation is running or not.
`paused` | boolean |  | Whether the simulation is paused.
`animation_frame_id` | number | <nullable> | The id of the agentmap's update function in the queue of functions to call for the coming animation frame.
`ticks` | number | <nullable> | The number of ticks elapsed since the start of the simulation.
`animation_interval` | number |  | The number of steps agents must move before being redrawn. Given 1, they will be redrawn after every step. Given 0, the animation will not update at all. 1 by default. Will be a nonnegative integer.
`controller` | function | <nullable> | User-defined function to be called on each update.

Source:
  - agentmap.js, line 6

### Methods

#### (private, static) checkAnimIntervalOption(animation_interval)

Check whether the animation interval option provided is valid.

##### Parameters:

Name | Type | Description
--- | --- | ---
`animation_interval` | number | An input specifying an animation interval distance.

Source:
  - agentmap.js, line 61

#### agentify(count, agentFeatureMaker)

Generate some number of agents and place them on the map.

##### Parameters:

Name | Type | Description
--- | --- | ---
`count` | number | The desired number of agents.
`agentFeatureMaker` | agentFeatureMaker | A callback that determines an agent i's feature properties and geometry (always a Point).

Source:
  - agents.js, line 737

#### buildingify(bounding_box, streets_data, street_optionsopt, unit_optionsopt, units_dataopt)

Generate and setup the desired map features (e.g. streets, houses).

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`bounding_box` | Array.<Array.<number>> |  | The map's top-left and bottom-right coordinates.
`streets_data` | object |  | A GeoJSON Feature Collection object containing the OSM street features inside the bounding box.
`street_options` | object | <optional> | An object containing the Leaflet styling options for streets. See available options here: https://leafletjs.com/reference-1.3.2.html#polyline-l-polyline.
`unit_options` | object | <optional> | An object containing the Leaflet & AgentMaps styling options for units. See available Leaflet options here: https://leafletjs.com/reference-1.3.2.html#polygon-l-polygon Additional AgentMaps-specific options are described below. ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`front_buffer` | number | <optional> | 6 | The number of meters beetween the front of unit and its street.
`side_buffer` | number | <optional> | 3 | The number of meters between two units on the same street.
`length` | number | <optional> | 14 | The length of the unit in meters along the street.
`depth` | number | <optional> | 18 | The depth of the unit in meters out from its front.
`units_data` | object | <optional> | If you want to load a previously generated AgentMaps.units object instead of generating one from scarch: A GeoJSON Feature Collection of an AgentMaps.units featureGroup.

Source:
  - buildings.js, line 27

#### clear()

Stop the animation, reset the animation state properties, and delete the features.

Source:
  - agentmap.js, line 110

#### downloadUnits()

Since units may take a noticeably long time to generate while typically staying the same over simulations, downloadUnits makes it easy to get a JS file containing the units object, so it can be included with an AgentMaps app and imported into Agentmap.buildingify so they will not need to be regenerated.

Source:
  - agentmap.js, line 261

#### getNearestIntersection(lat_lng, place) → {LatLng}

Given a point on a street, find the nearest intersection on that street (with any other street).

##### Parameters:

Name | Type | Description
--- | --- | ---
`lat_lng` | LatLng | The coordinates of the point on the street to search from.
`place` | Place | A place object corresponding to the street.

Source:
  - agentmap.js, line 215

##### Returns:

- The coordinates of the nearest intersection.

Type
  LatLng

#### (private) getPath(start_int_lat_lng, goal_int_lat_lng, start_lat_lng, goal_lat_lng, sparseopt) → {Array.<Array.<number>>}

Get a path between two points on a graph.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`start_int_lat_lng` | LatLng |  |  | The coordinates of the nearest intersection on the same street at the start_lat_lng.
`goal_int_lat_lng` | LatLng |  |  | The coordinates of the nearest intersection on the same street as the goal_lat_lng.
`start_lat_lng` | LatLng |  |  | The coordinates of the point on the street from which the agent will be traveling.
`goal_lat_lng` | LatLng |  |  | The coordinates of the point on the street to which the agent should travel.
`sparse` | Boolean | <optional> | false | Whether to exclude intersections between the first and last along a street-specific path (which are superfluous for extracting the necessary sub-street).

Source:
  - routing.js, line 113

##### Returns:

- An array of points along the graph, leading from the start to the end.

Type
  Array.<Array.<number>>

#### getStreetNearDoor(unit_id) → {LatLng}

Get the point on the adjacent street in front of the unit's door.

##### Parameters:

Name | Type | Description
--- | --- | ---
`unit_id` | number | The unique ID of the unit whose door's corresponding point on the street you want.

Source:
  - agentmap.js, line 158

##### Returns:

- The coordinates point of the adjacent street directly in front of unit's door.

Type
  LatLng

#### getUnitDoor(unit_id) → {LatLng}

Get a point through which an agent can exit/enter a unit.

##### Parameters:

Name | Type | Description
--- | --- | ---
`unit_id` | number | The unique ID of the unit whose door you want.

Source:
  - agentmap.js, line 137

##### Returns:

- The coordinates of the center point of the segment of the unit parallel to the street.

Type
  LatLng

#### getUnitPoint(unit_id, x, y) → {LatLng}

Given a unit and a pair of coordinates between 0 and 1, return a corresponding point inside the unit, offset from its first corner along the street.

##### Parameters:

Name | Type | Description
--- | --- | ---
`unit_id` | number | The unique ID of the unit whose interior point you want.
`x` | number | A point between 0 and 1 representing a position along the width of a unit.
`y` | number | A point between 0 and 1 representing a position along the depth of a unit.

Source:
  - agentmap.js, line 179

##### Returns:

- The global coordinates of the specified position within the unit.

Type
  LatLng

#### pause()

Stop the animation, stop updating the agents.

Source:
  - agentmap.js, line 125

#### run()

Get an animation frame, have the agents update & get ready to be drawn, and keep doing that until paused or reset.

Source:
  - agentmap.js, line 70

#### seqUnitAgentMaker()

A standard agentFeatureMaker, which sets an agent's location to be the point near the center of the iᵗʰ unit of the map, its place property to be that unit's, and its layer_options to be red and of radius .5 meters.

Source:
  - agents.js, line 713

#### setAnimationInterval(animation_interval)

Change the animation interval of the simulation & redraw the agents.

##### Parameters:

Name | Type | Description
--- | --- | ---
`animation_interval` | number | The desired animation interval to give the simulation. Must be a nonnegative integer.

Source:
  - agentmap.js, line 47

#### (private) update()

Update the simulation at the given time.

Source:
  - agentmap.js, line 91