Drawing Vectors on the Screen¶

You can create an object that represents a vector drawn in the flight view, as a holographic image in flight. You may move it to a new location, make it appear or disappear, change its color, and label. This page describes how to do that.

VECDRAW(start, vec, color, label, scale, show, width)¶

VECDRAWARGS(start, vec, color, label, scale, show, width)¶

Both these two function names do the same thing. For historical reasons both names exist, but now they both do the same thing. They create a new vecdraw object that you can then manipulate to show things on the screen:

SET anArrow TO VECDRAW(
      V(0,0,0),
      V(a,b,c),
      RGB(1,0,0),
      "See the arrow?",
      1.0,
      TRUE,
      0.2
    ).

SET anArrow TO VECDRAWARGS(
      V(0,0,0),
      V(a,b,c),
      RGB(1,0,0),
      "See the arrow?",
      1.0,
      TRUE,
      0.2
    ).

All the parameters of the VECDRAW() and VECDRAWARGS() are optional. You can leave any of the lastmost parameters off and they will be given a default:

Set anArrow TO VECDRAW().

Causes it to have these defaults:

Defaults¶

Suffix	Default
START	V(0,0,0) (center of the ship is the origin)
VEC	V(0,0,0) (no length, so nothing appears)
COLO[U]R	White
LABEL	Empty string “”
SCALE	1.0
SHOW	false
WIDTH	0.2

Examples:

// Makes a red vecdraw at the origin, pointing 5 meters north,
// with defaults for the un-mentioned
// paramters LABEL, SCALE, SHOW, and WIDTH.
SET vd TO VECDRAW(V(0,0,0), 5*north:vector, red).

To make a VecDraw disappear, you can either set its VecDraw:SHOW to false or just UNSET the variable, or re-assign it. An example using VecDraw can be seen in the documentation for POSITIONAT().

CLEARVECDRAWS()¶

Sets all visible vecdraws to invisible, everywhere in this kOS CPU. This is useful if you have lost track of the handles to them and can’t turn them off one by one, or if you don’t have the variable scopes present anymore to access the variables that hold them. The system does attempt to clear any vecdraws that go “out of scope”, however the “closures” that keep local variables alive for LOCK statements and for other reasons can keep them from every truely going away in some circumstances. To make the arrow drawings all go away, just call CLEARVECDRAWS() and it will have the same effect as if you had done SET varname:show to FALSE for all vecdraw varnames in the entire system.

structure VecDraw¶

This is a structure that allows you to make a drawing of a vector on the screen in map view or in flight view.

Members¶

Suffix	Type	Description
START	Vector	Start position of the vector
VEC	Vector	The vector to draw
COLOR	Color	Color of the vector
COLOUR		Same as COLOR
LABEL	string	Text to show next to vector
SCALE	scalar	Scale VEC and WIDTH but not START
SHOW	boolean	True to enable display to screen
WIDTH	scalar	width of vector, default is 0.2

VecDraw:START¶

Access:	Get/Set
Type:	Vector

Optional, defaults to V(0,0,0) - position of the tail of the vector to draw in SHIP-RAW coords. V(0,0,0) means the ship Center of Mass.

VecDraw:VEC¶

Access:	Get/Set
Type:	Vector

Mandatory - The vector to draw, SHIP-RAW Coords.

VecDraw:COLOR¶

Access:	Get/Set
Type:	Color

Optional, defaults to white. This is the color to draw the vector. There is a hard-coded fade effect where the tail is a bit more transparent than the head.

VecDraw:COLOUR¶

Access:	Get/Set
Type:	Color

Alias for VecDraw:COLOR

VecDraw:LABEL¶

Access:	Get/Set
Type:	string

Optional, defaults to “”. Text to show on-screen at the midpoint of the vector. Note the font size the label is displayed in gets stretched when you change the SCALE or the WIDTH values.

VecDraw:SCALE¶

Access:	Get/Set
Type:	scalar

Optional, defaults to 1.0. Scalar to multiply the VEC by, and the WIDTH, but not the START.

Changed in version 0.19.0: In previous versions, this also moved the start location, but most users found that useless and confusing and that has been changed as described above.

VecDraw:SHOW¶

Access:	Get/Set
Type:	boolean

Set to true to make the arrow appear, false to hide it. Defaults to false until you’re ready to set it to true.

VecDraw:WIDTH¶

Access:	Get/Set
Type:	scalar

Define the width of the drawn line, in meters. The deafult is 0.2 if left off. Note, this also causes the font of the label to be enlarged to match if set to a value larger than 0.2.

New in version 0.19.0: This parameter didn’t exist before kOS 0.19.0.