annotation([plotobj::DisplazWindow,] coords::Array{T,1}, text::String, label=text::String)

Place a text annotation at given coordinates

If not specified, plotobj is the current plot window. coords is a three element array [x, y, z], text is the text to plot and label its Displaz label, note annotation labels don't appear in Displaz's list of data sets they are needed however to unload an annotation. If unspecified the label defaults to the annotation string.

clearplot([plotobj::DisplazWindow=current()], [pattern1, ...])

Clear all or a subset of datasets in a plot window.

If not specified, plotobj is the current plot window. If no patterns are supplied, clears all data sets. If one or more patterns are given, the dataset labels matching those patterns will be removed. Patterns shoudl be specified using unix shell glob pattern syntax.

Get handle to current figure window

event_loop(callback::Function, [plotobj::DisplazWindow], event_list...)

Subscribe to a list of events, calling callback each time one is received.

Each event comes with some optional some state which is attached at the time the event is triggered. The events are specified as a list of event=>state pairs.

Currently only KeyEvent is supported, with the possible arguments Nothing or CursorPosition. For example:

Displaz.event_loop(
        KeyEvent("c")=>Nothing,
        KeyEvent("p")=>CursorPosition
) do event, arg
    @show event, arg
    if event == KeyEvent("c")
        clearplot()
    end
end

Get figure window by name may be new or already existing

Get figure window with given id

mutate!([plotobj,] label, index; attr1=value1, ...))

Mutate the data in an existing displaz data set label, for instance to change the position or other attribute of a subset of points (with the advantage of reducing the amount of communication between Julia and displaz, and therefore increasing speed).

index is vector of indices with reference to the original plot. The attribute label is used to match with the correct data set within displaz. The position attribute controls the vertex positions, and the remainder match the original plotting command.

Create next incrementally named figure window, counting automatically from "Figure 1"

Overwrite points or lines with the same label on the 3D plot

See plot3d for documentation

Add 3D points or lines to the current plot.

  plot3d([plotobj,] position; attr1=value1, ...)

The position array should be a set of N vertex positions, specified as 3xN array or a Vector of FixedVector{3}. The plotobj argument is optional and determines which plot window to send the data to. If it's not used the data will be sent to the plot window returned by current().

TODO: Revisit the nasty decision of the shape of position again - the above choice is somewhat inconsistent with supplying markersize / markershape as a column vector :-( Can we have a set of consistent broadcasting rules for this? It seems like the case of a 3x3 matrix will always be ambiguous if we try to guess what the user wants.

Data set attributes

The following attributes can be attached to a dataset on each call to plot3d:

• label - A string labeling the data set

Vertex attributes

Each point may have a set of vertex attributes attached to control the visual representation and tag the point for inspection. You can pass any Vector of Float32 values for any custom information you like, but the following are supported by the default shader:

• color - A color or vector of colors for each point; see below for ways to specify these.
• intensity - A vector of the intensity of each point (between 0 and 1)
• markersize - Vertex marker size
• markershape - Vector of vertex marker shapes. Shape can be represented either by a Char or a numeric identifier between 0 and 4:

                    sphere - '.' 0    square - 's' 1
                    circle - 'o' 2    times  - 'x' 3
                    cross  - '+' 4

Specifying colors

Colors may be provided in any of three ways:

• As instances of types from the ColorTypes package, for example, HSV(180,1,1). These are converted to RGB using the RGB constructor.
• As a Vector of three elements, red, green and blue, between 0.0 and 1.0.
• Using a matlab-like single color letter name string or Char. Supported are red, green, blue, cyan, magenta, yellow, black and white; all are abbreviated with the first letter of the color name except black for which 'k' is used.

A color per point may be supplied as a Vector of Color subtypes or a 3xN matrix with red, green and blue in the rows.

Plotting points

To plot 10000 random points with distance from the origin determining the color, and random marker shapes:

  P = randn(3,10000)
  c = 0.5./sumabs2(P,1) .* [1,0,0]
  plot3d(P, color=c, markershape=rand(1:4,10000))

Plotting lines

To plot a piecewise linear curve between 10000 random vertices

  plot3d(randn(3,10000), markershape="-")

When plotting lines, the linebreak keyword argument can be used to break the position array into multiple line segments. Each index in the line break array is the initial index of a line segment.

Overwrite images with the same label

See plotimage for documentation

Add images to the current plot.

  plotimage([plotobj,] texturefile, vertices; label=nothing, _overwrite_label=false)

The texturefile string should include the path (relative or absolute) to the image to be loaded (if not in the current folder). The vertices array should be a set of vertex positions specifying the corners of the image to plot. The order is anticlockwise starting from bottom left (i.e. (0,1), (1,1), (1,0), (0,0) in texture coordinates), and the vertices should be specified as a 3x4 array. The plotobj argument is optional and determines which plot window to send the data to. If it's not used the data will be sent to the plot window returned by current().

set_displaz_cmd(cmd)

Set name or full path for where the displaz binary will be found to cmd. Defaults to the environment variable DISPLAZ_CMD, or the string "displaz" if that variable is not found.

viewplot([plotobj::DisplazWindow=current()];
         center=point_or_label, radius=dist_from_center, rotation=rot_matrix)

Set the point of view of the 3D camera. The camera model is designed to view an object at a given center of rotation, with rotations pivoting around that position.

If not specified, plotobj is the current plot window. Keyword arguments define the camera view as follows:

• The center argument may be a 3D point or the label of a data set. If a label is supplied the centroid of the associated dataset will be used.
• The radius argument should be a number giving the distance that the camera will be away from the center of rotation.
• The rotation argument specifies the angles at which the camera will view the scene. This can be a matrix transforming points into the standard OpenGL camera coordinates (+x right, +y up, -z into the scene). Alternatively you may supply a tuple (yaw, pitch, roll) in degrees which is equivalent to using the rotation matrix RotZXZ(deg2rad(roll), deg2rad(pitch-90), deg2rad(yaw)) from Rotations.jl.