Lasso

The lasso plugin allows users to select nodes, group and edges with the mouse. We've activated it on page load so you can try it out below. After you've tried it once the surface will revert to pan mode and you'll need to select the lasso from the controls.

Any vertices snagged by your lasso are added to the model's current selection.

The lasso works like the lasso in AutoCAD: when you drag from left to right, any vertices that intersect with your lasso are added to the selection. When you drag from right to left, though, only vertices that your lasso fully encloses are added to the selection.

When the user lassos outside of the visible area, the lasso will automatically pan the canvas.

Setup

The lasso plugin does not need any options set in order to function, so the simplest setup is just to reference it in the plugin list:

<script setup>

import { LassoPlugin } from "@visuallyjs/browser-ui"

const renderOptions = {
  plugins: [
    LassoPlugin.type
  ]
}


</script>
<template>
  <SurfaceComponent :renderOptions="renderOptions" />
</template>

Lasso modes

The default mode for a lasso is to draw a rectangular selection region, but you can also choose freehand or polygon.

Freehand

In this mode, the user draws freehand on the canvas and the lasso is computed from the area that the user has outlined - click and drag in the canvas below to enclose an area. Any vertices intersecting the area you have selected will be added to the selection.

<script setup>

const renderOptions = {
  plugins: [
    {
      type: "lasso",
      options: {
        shape: "freehand"
      }
    }
  ]
}


</script>
<template>
  <SurfaceComponent :renderOptions="renderOptions" />
</template>

Polygon

In this mode, the user draws freehand on the canvas and the lasso is computed from the area that the user has outlined - click on the canvas below to specify the points for the polygon (you won't see a shape start to form until you've clicked 3 times). To cancel the lasso, either press Escape or right-click. To finish the lasso operation, either double-click or press Enter.

<script setup>

const renderOptions = {
  plugins: [
    {
      type: "lasso",
      options: {
        shape: "polygon"
      }
    }
  ]
}


</script>
<template>
  <SurfaceComponent :renderOptions="renderOptions" />
</template>

Mask lasso

The lasso, by default, draws a rectangle over the canvas, but VisuallyJs can also draw the lasso as a set of overlays which mask the whole browser window except for the lassoed area - to do this, set invert:true:

<script setup>

const renderOptions = {
  plugins: [
    {
      type: "lasso",
      options: {
        invert: true
      }
    }
  ]
}


</script>
<template>
  <SurfaceComponent :renderOptions="renderOptions" />
</template>

Auto arm

Since: 1.2.4

The lasso supports the concept of "auto arm" - the lasso will arm itself if the user long-presses on the canvas. Try pressing and holding the left mouse button on this canvas. After 500ms, you will see the controls component switch to show that the lasso is engaged:

<script setup>

const renderOptions = {
  plugins: [
    {
      type: "lasso",
      options: {
        autoArm: true
      }
    }
  ]
}


</script>
<template>
  <SurfaceComponent :renderOptions="renderOptions" />
</template>

Auto arm timeout

The default timeout is 500ms before the lasso will arm itself. In some use cases you might want to reduce that time, which you can do via the armTimeout option on the lasso. One such use case, for instance, is when you've setup your canvas to use the wheel for pan instead of zoom - in the canvas below, the wheel pans the content, and the armTimeout is set to 0 for the lasso, so it switches on as soon as you begin to drag with the left mouse button:

<script setup>

const renderOptions = {
  plugins: [
    {
      type: "lasso",
      options: {
        autoArm: true,
        armTimeout: 0
      }
    }
  ]
}


</script>
<template>
  <SurfaceComponent :renderOptions="renderOptions" />
</template>

You can also, of course, choose to reduce the armTimeout without altering the behaviour of the wheel.

CSS Classes

Class	Description
vjs-lasso	Assigned to the DOM element representing a lasso
vjs-lasso-mask	Assigned to each DOM element representing part of the lasso mask, when the lasso is inverted mode. The lasso mask consists of four parts, one to the left, right, top and bottom of the area that has been lassoed.
vjs-lasso-mask-bottom	Assigned to the DOM element representing the bottom part of the lasso mask, when the lasso is inverted mode.
vjs-lasso-mask-left	Assigned to the DOM element representing the left part of the lasso mask, when the lasso is inverted mode.
vjs-lasso-mask-right	Assigned to the DOM element representing the right part of the lasso mask, when the lasso is inverted mode.
vjs-lasso-mask-top	Assigned to the DOM element representing the top part of the lasso mask, when the lasso is inverted mode.

Options

LassoPluginOptions

Name	Type	Description
armTimeout?	number	Timeout in ms for autoArm long press. Defaults to 500ms.
autoArm?	boolean	Defaults to false. If true, the lasso will arm itself after a long press.
autoExit?	boolean	When true (which is the default) the lasso exits after a selection has been made.
cssClass?	string	Extra class(es) to add to the lasso's DOM element
enableInGroups?	boolean | "metaKey"	Optional setting for whether lasso inside groups is enabled - it is by default. Setting this to false will mean that the user cannot lasso items inside a group. Setting to "metaKey" will mean that lasso is supported inside groups if the user is holding the meta key down (ie the Window key, or Cmd on macs).
filter?	string | (e:MouseEvent) => boolean	Optional CSS3 filter identifying elements you do not want to lasso
generateLassoContent?	(origin:PointXY, e:MouseEvent) => BrowserElement	Optional function that generates the DOM element for the lasso to use. This is for advanced usage scenarios and most users will not need to supply this. Applies only to rectangular lasso; freehand and polygon use a built-in SVG path styled with the lasso CSS variables/classes.
includeEdges?	boolean	Defaults to false. If true, edges are included in the lasso selection.
invert?	boolean	Defaults to false. If true, shade outside the selected region instead of inside it.
onEnd?	Function	Optional function to call when lasso selection ends. Polygon gestures supply {shape:"polygon", cancelled:boolean} for completion or cancellation.
onSelect?	(vertices:Array<Vertex>) => any	Optional function to call when one or more objects has been selected by the lasso.
onStart?	Function	Optional function to call when lasso selection starts.
selectionFilter?	(o:Edge | Vertex) => boolean	Optional filter that is passed every vertex/edge that the lasso would ordinarily select, and if this function returns false then the vertex/edge is not added to the selection
shape?	LassoShape	Selection shape. Defaults to "rectangle". "freehand" draws continuously; "polygon" adds vertices on clicks and completes with double-click or Enter.
simplificationTolerance?	number	Corner-preserving freehand simplification tolerance in screen pixels. Defaults to 1. Must be finite and non-negative; 0 disables simplification. Details smaller than this tolerance may disappear.