Labelgun

https://geovation.github.io/labelgun/
Admin
Labelgun is a mapping library agnostic labelling engine designed to avoid clutter in map popups and...
Tokens:4,323
Snippets:36
Trust Score:9.7
Update:3 days ago
Show doc for...
Tokens:
Raw
### _setupLabels method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Initializes or updates the spatial tree based on whether all labels changed or only a subset.

```javascript
_setupLabels() {

    if(this.allChanged) {

      this.allChanged = false;
      this.hasChanged = [];
      this.tree.clear();

      let labels = [];
      for(let key in this.allLabels) {
        this._handleLabelIngestion(key);
        labels.push(this.allLabels[key]);
      }

      this.tree.load(labels);

    }
    else if(this.hasChanged.length > 0) {

      this.hasChanged.forEach(id => {
        this._handleLabelIngestion(id);
        this.tree.insert(this.allLabels[id]);
      });

      this.hasChanged = [];

    }

  }
```

--------------------------------

### getShown()

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Returns an array of all shown labels.

```APIDOC
## getShown()

### Description
Returns an array of all shown labels.

### Returns
- **array** - An array of shown labels.
```

--------------------------------

### update method implementation

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Sets allChanged based on onlyChanges parameter, then reruns the show/hide procedure by calling _setupLabels, _compareLabels, and _callLabelCallbacks.

```javascript
  update(onlyChanges) {

    if (onlyChanges) {
      this.allChanged = false;
    } else {
      this.allChanged = true;
    }
    
    this._setupLabels();
    this._compareLabels();
    this._callLabelCallbacks();

  }
```

--------------------------------

### _compareLabels method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Sorts labels by weight and determines which should be shown based on collision detection.

```javascript
_compareLabels() {

    // Map all the labels to an array and sort based on weight
    // highest to lowest

    this.orderedLabels = [];
    for(let key in this.allLabels) {
      this.orderedLabels.push(this.allLabels[key]);
    }
    this.orderedLabels.sort(this._compare);

    this.orderedLabels.forEach((label) => {

      const collisions = this.tree.search(label);
      
      if (collisions.length === 0 || label.isDragged || this._allLower(collisions, label)) {
        this.allLabels[label.id].state = "show";
      }

    });
  }
```

--------------------------------

### new labelgun(hideLabel, showLabel, entries)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Creates a new labelgun instance with callbacks for hiding and showing labels.

```APIDOC
## new labelgun(hideLabel, showLabel, entries)

### Description
Creates a new labelgun instance with the provided hide and show label callbacks.

### Parameters
- **hideLabel** (function) - Required - The function responsible for hiding the label on hide event.
- **showLabel** (function) - Required - The function responsible for showing the label on show event.
- **entries** (number) - Required - Higher value relates to faster insertion and slower search, and vice versa.

### Returns
No return value.
```

--------------------------------

### ingestLabel(boundingBox, id, weight, labelObject, labelName, isDragged)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Creates a label if it does not already exist, adds it to the tree, and renders it based on whether it can be shown.

```APIDOC
## ingestLabel(boundingBox, id, weight, labelObject, labelName, isDragged)

### Description
Creates a label if it does not already exist, then adds it to the tree, and renders it based on whether it can be shown.

### Parameters
- **boundingBox** (object) - Required - The bounding box object with bottomLeft and topRight properties.
- **id** (string) - Required - The id of the label.
- **weight** (number) - Required - The weight to compare labels in the collision resolution.
- **labelObject** (object) - Required - The object representing the actual label object from your mapping library.
- **labelName** (string) - Required - A string depicting the name of the label.
- **isDragged** (boolean) - Required - A flag to say whether the label is being dragged.

### Returns
No return value.
```

--------------------------------

### totalShown()

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Returns the total number of shown labels.

```APIDOC
## totalShown()

### Description
Returns the total number of shown labels.

### Returns
- **number** - Total number of labels shown.
```

--------------------------------

### _handleLabelIngestion method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Helper to ingest label coordinates and metadata into the spatial tree.

```javascript
_handleLabelIngestion(id) {
    const label = this.allLabels[id];
        
    this.ingestLabel(
      {
        bottomLeft: [label.minX, label.minY],
        topRight: [label.maxX, label.maxY]
      },
      label.id,
      label.weight,
```

--------------------------------

### ingestLabel method implementation

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Creates a label if it does not exist, adds it to the tree, and renders it based on whether it can be shown. Validates bounding box and id type, throws errors if invalid.

```javascript
  ingestLabel(boundingBox, id, weight, labelObject, labelName, isDragged) {

    // Add the new label to the tree
    if (weight === undefined || weight === null) {
      weight = 0;
    } 

    if (!boundingBox || !boundingBox.bottomLeft || !boundingBox.topRight) {
      throw Error("Bounding box must be defined with bottomLeft and topRight properties");
    }

    if (typeof id !== "string" && typeof id !== "number") {
      throw Error("Label IDs must be a string or a number");
    }

    // If there is already a label in the tree, remove it
    const oldLabel = this.allLabels[id];
    if (oldLabel) this.removeLabel(oldLabel.id, oldLabel);

    const label = {
      minX: boundingBox.bottomLeft[0],
      minY: boundingBox.bottomLeft[1],
      maxX: boundingBox.topRight[0],
      maxY: boundingBox.topRight[1],
      state: "hide",
      id : id,
      weight: weight,
      labelObject : labelObject,
      name : labelName,
      isDragged : isDragged
    };

    //We just store the label into the array. The tree is built when updated
    this.allLabels[label.id] = label;

  }
```

--------------------------------

### _compare method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Comparator function to sort labels by weight in descending order.

```javascript
_compare(a,b) {
    // High to Low
    return b.weight - a.weight;
  }
```

--------------------------------

### _callLabelCallbacks method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Iterates through all labels and triggers the appropriate state callback for each.

```javascript
_callLabelCallbacks(forceState) {
    for(let key in this.allLabels) {
      this._callLabelStateCallback(this.allLabels[key], forceState);
    }
  }
```

--------------------------------

### update(onlyChanges)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Sets all or some of the labels to change and reruns the whole show/hide procedure.

```APIDOC
## update(onlyChanges)

### Description
Sets all or some of the labels to change and reruns the whole show/hide procedure.

### Parameters
- **onlyChanges** (boolean) - Required - Whether to only update the changes made by labelHasChanged.

### Returns
No return value.
```

--------------------------------

### reset()

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Destroys the collision tree and labels.

```APIDOC
## reset()

### Description
Destroys the collision tree and labels.

### Returns
No return value.
```

--------------------------------

### _callLabelStateCallback method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Calls the show or hide callback for a specific label based on its current or forced state.

```javascript
_callLabelStateCallback(label, forceState) {
    const state = forceState || label.state;
    if (state === "show") this.showLabel(label);
    if (state === "hide") this.hideLabel(label);
  }
```

--------------------------------

### getHidden()

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Returns an array of all hidden labels.

```APIDOC
## getHidden()

### Description
Returns an array of all hidden labels.

### Returns
- **array** - An array of hidden labels.
```

--------------------------------

### Labelgun Class Definition

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

The main class for managing label visibility, requiring hide and show callbacks and an optional entries parameter for the RBush index.

```javascript
import rbush from "rbush";

/**
* @summary create a label gun instance with a hide and show label callback
* @param {function} hideLabel the function responsible for hiding the label on hide event
* @param {function} showLabel the function responsible for showing the label on show event
* @param {number} entries Higher value relates to faster insertion and slower search, and vice versa
*/
class labelgun {

 

  constructor(hideLabel, showLabel, entries) {

    const usedEntries = entries || 10;
    this.tree = rbush(usedEntries);
    this.allLabels = {};
    this.hasChanged = [];
    this.allChanged = false;
    this.hideLabel = hideLabel;
    this.showLabel = showLabel;
  }

  /**
   * @name _total
   * @summary get the total hidden or shown labels in the tree
   * @memberof labelgun.prototype
   * @param {string} state whether to return 'hide' or 'show' state label totals
   * @returns {number} total number of labels of that state
   * @private
   */
  _total(state) {
    let total = 0;
    for (let key in this.allLabels) {
      if (this.allLabels[key].state == state) {
        total += 1;
      }
    }
    return total;
  }



  /**
   * @name totalShown
   * @memberof labelgun
   * @method
   * @summary Return the total number of shown labels
   * @returns {number} Return total number of labels shown
   * @public
   */
  totalShown() {
    return this._total("show");
  }



  /**
   * @name totalHidden
   * @memberof labelgun
   * @method
   * @summary Return the total number of hidden labels
   * @returns {number} Return total number of labels hidden
   * @public
   */
  totalHidden() {
    return this._total("hide");
  }

  /**
   * @name getLabelsByState
   * @summary Provided a state get all labels of that state
   * @param {string} state - the state of the labels to get (show or hide)
   * @returns {array} Labels that match the given state (show or hide)
   * @private
   */
  _getLabelsByState(state) {
    const labels = [];
    for (let key in this.allLabels) {
      if (this.allLabels[key].state == state) {
        labels.push(this.allLabels[key]);
      }
    }
    return labels;
  }

  /**
   * @name getHidden
   * @memberof labelgun
   * @method
   * @summary Return an array of all the hidden labels
   * @returns {array} An array of hidden labels
   */
  getHidden() {
    return this._getLabelsByState("hide");
  }

  /**
   * @name getShown
   * @memberof labelgun
   * @method
   * @summary Return an array of all shown labels
   * @returns {array} An array of shown label
   */
  getShown() {
    return this._getLabelsByState("show");
  }

  /**
   * @name getCollisions
   * @memberof labelgun
   * @method
   * @summary Return a set of collisions (hidden and shown) for a given label
   * @param {string} id - the ID of the label to get
   * @returns {array} The list of collisions
   */
  getCollisions(id) {

    const label = this.allLabels[id];
    if (label === undefined) {
      throw Error("Label doesn't exist :" + JSON.stringify(id));
    }

    const collisions =  this.tree.search(label);
    const self = collisions.indexOf(label);

    // Remove the label if it's colliding with itself
    if (self !== undefined) collisions.splice(self, 1);
    return collisions;
  }

  /**
   * @name getLabel
   * @memberof labelgun
   * @method
   * @summary Convenience function to return a label by ID
   * @param {string} id the ID of the label to get
   * @returns {object} The label object for the id
   */
  getLabel(id) {
    return this.allLabels[id];
  }

  /**
   * @name reset
   * @memberof labelgun
   * @method
   * @summary Destroy the collision tree and labels
   * @returns {undefined}
   */
  reset() {
    this.tree.clear();
    this.allLabels = {};
    this.hasChanged = [];
    this.allChanged = false;
  }

  /**
   * @name _callLabelCallbacks
   * @memberof labelgun
   * @method
   */
```

--------------------------------

### _allLower method

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Checks if all colliding labels have lower priority, are already shown, or are being dragged.

```javascript
_allLower(collisions, label) {
    let collision;
    for (let i = 0; i < collisions.length; i++) {
      collision = collisions[i];
      if (
        collision.state === "show" || 
        collision.weight > label.weight || 
        collision.isDragged
      ) {
        return false;
      }
    }

    return true;
  }
```

--------------------------------

### totalHidden()

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Returns the total number of hidden labels.

```APIDOC
## totalHidden()

### Description
Returns the total number of hidden labels.

### Returns
- **number** - Total number of labels hidden.
```

--------------------------------

### getLabel(id)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Convenience function to return a label by ID.

```APIDOC
## getLabel(id)

### Description
Convenience function to return a label by ID.

### Parameters
- **id** (string) - Required - The ID of the label to get.

### Returns
- **object** - The label object for the id.
```

--------------------------------

### getCollisions(id)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Returns a set of collisions (hidden and shown) for a given label.

```APIDOC
## getCollisions(id)

### Description
Returns a set of collisions (hidden and shown) for a given label.

### Parameters
- **id** (string) - Required - The ID of the label to get.

### Returns
- **array** - The list of collisions.
```

--------------------------------

### removeLabel method implementation

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Removes a label from the tree and deletes it from the allLabels object. Uses the provided label or looks up by id.

```javascript
  removeLabel(id, label) {
    this.tree.remove(label || this.allLabels[id]);
    delete this.allLabels[id];
  }
```

--------------------------------

### labelHasChanged(id)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Lets labelgun know the label has changed in some way (e.g., its state or that it is dragged).

```APIDOC
## labelHasChanged(id)

### Description
Lets labelgun know the label has changed in some way (e.g., its state or that it is dragged).

### Parameters
- **id** (string) - Required - The id of the label that has changed in some way.

### Returns
No return value.
```

--------------------------------

### labelHasChanged method implementation

Source: https://geovation.github.io/labelgun/documentation/labelgun.js.html

Adds the given id to the hasChanged array if it is not already present, letting labelgun know the label has changed.

```javascript
  labelHasChanged(id) {
    if (this.hasChanged.indexOf(id) === -1) {
      this.hasChanged.push(id);
    }
  }
```

--------------------------------

### removeLabel(id, label)

Source: https://geovation.github.io/labelgun/documentation/labelgun.html

Removes a label from the tree and allLabels object.

```APIDOC
## removeLabel(id, label)

### Description
Removes a label from the tree and allLabels object.

### Parameters
- **id** (string) - Required - The label id for the label to remove from the tree.
- **label** (object) - Required - The label to remove from the tree.

### Returns
No return value.
```
Tokens:
Raw