Spline Drawing Tool For MATLAB

Ali Rahimi (last modified 7 Aug 2005)


This tool allows you to interactively draw and manipulate 2D polylines and splines, a little bit like what you might do in a vector drawing program like MacDraw or Illustrator. I built it to help me ovelay splines on image sequences.

Two tools are included in this package

  • spltool.m: a single frame spline tool.
  • annotate2.m: a video sequence spline tool lets you conveniently apply spltool to the frames of a video sequence.

    • The spltool leaves your MATLAB prompt free, so that you can invoke MATLAB commands while you're editing the drawing. You can then retrieve the current drawing as a MATLAB array and process it, or save it for later editing.

    Spltool: Drawing Interface

    The spline tool lets you draw two kinds of shapes: polylines and splines. Both are defined by control points, which define either corners of the polyline, or knots of the spline. You can interactively drag control points with the mouse to reshape the shapes, click to define new control points, or create new shapes. You can change various attributes of the shapes, such as color, whether they are closed, filled, or whether the control points should serve as knots to define a spline, or as corners to define a polyline. The tool also maintains a stacking order so that overlapping shapes can be pushed behind or in pulled in front of others.

    An active shape being modified Toggling from spline to polyline Toggling the fill on a shape
    Colors can be changed Shapes can be pushed up or down in the stacking order

    The commands are:

  • click on inactive shape: makes it active (draws draggable handles on its control points).
  • drag control point: reshape.
  • CTRL-drag shape: moves entire shape. Note, you must CTRL-drag the shape, not a control point.
  • SHIFT-drag: moves all shapes. you do not need to click on any one shape for this.
  • ESC: deactivate the shape (removes the draggable handles).
  • c: toggle whether the shape is closed (first control point also serves as the last control point) or open.
  • s: toggle between making the shape a spline or a polyline.
  • f: toggle between making the shape filled or unfilled.
  • DEL: delete last control point of active shape.
  • p: invoke color picker to change color of active shape.
  • +: move shape up in the stacking order.
  • -: move shape down in the stacking order.
  • 0..9: set the shape's stack level to the value of the key.
  • q: quits the tool. deregisters the event callbacks on the window, and calls uiresume in case the invoking code has blocked on spltool with a uiwait.

    Spltool: Programming Interface

    You can start editing by calling spltool('init'). This command installs event handlers on the current figure and begins listening for key strokes and button presses. The command does not block, so you can keep typing commands at the MATLAB prompt. If you want the command the block, you can execute uiwait: spltool will call uiresume when you quit it.

    To retrieve the art work you've drawn in the figure, call spltool('save'). This will return an array of shape data structures that is easy to manipulate. It's so easy to understand that I won't bother documenting it here.

    You can reload old work by running spltool('modify',spls) where spls is in the same format as returned by spltool('save').

    You can load a background image by invoking spltool('bgimg',img), where img is displayed with imagesc.

    spltool('key',char) can be used to send a keystroke to the tool, instead of actually typing the key. This is used by the annotate2 tool to make spltool its canine subordinate.

    Annotate2: Interactive Interface

    Sometimes, you want to draw shapes on top of a sequence of images, instead of doodling on an empty canvas, or drawling shapes on a single image. annotate2 uses spltool as a subroutine.

    Once invoked, annotate2 understands the following keyboard commands in addition to all the spltool commands:

  • ],[ Move forward/backward to next/previous frame to annotate.
  • ),( Skip to next annotated frame / previous annotated frame.
  • SPC Clear all the shapes in this frame.
  • C Put current shapes in COPY buffer.
  • p Delete shapes for this image, and paste shapes in COPY buffer.
  • l Delete shapes for this image, and paste the shape in the last seen frame.
  • q quit.

    Annotate2: Invoking

    Invoke it with [list,spls] = annotate2(ipath,nums). Annotate remembers the annotations from the last time you invoked it. If you want to annotate from scratch, use annotate2(ipath,nums,[]).

    ipath is an sprintf format string to generate the file names of the images to be displayed in the background, and nums are the file numbers. annotate2 will generate file names to read from by using imread(sprintf(ipath,nums(i))) to load the ith image.

    For example, if you want to annotate the files /tmp/img/im010.png, /tmp/img/im011.png, /tmp/img/im012.png, /tmp/img/im013.png, and /tmp/img/im017.png, you would invoke

    annotate2('/tmp/img/im%03d.png', [10 11 12 13 17])

    The %03d format specifier tells sprintf to dedicate 3 characters for the integer index, and use the character 0 for padding.

    On return, spls is a cell array of spline data structures, as returned by spltool, one element per image. The entry will be empty for unannotated frames. list collects the control points using makesemilist (which is included in the package).

    You may optionally invoke with an additional spls, to specify old annotations you would like to update: [list,spls] = annotate2(ipath,nums,spls). But this is usually not necessary, because the returned spls from the last invokation of annotate2 will be stored in the figure's attribute structure, ready for annotate2 to retrieve.

    Software

    Note:MATLAB 7 is extremely buggy software. Especially on Windows. I recommend running this under MATLAB 6.5, and on a UNIX machine.

    Here is the archive. And here are the individual files. 

    spltool.m
annotate2.m
makesemilist.m (for you to extract numbers from spline descriptionts)
rendersplineseq.m (for you to generate videos of splines, overlayed on image sequences)
drawspline.m (rendering)
drawsplines.m (rendering)
renderspline.m (rendering)
orderlayers.m (utility)