Common Lisp Language Bindings

to the

Foundation and Virtual Ma hine Platform

Te hni al Report 92-2

Radiotherapy Treatment Planning Tools

Collaborative Working Group

Jonathan Ja ky
Ira Kalet
Mi hael Kahn
Steve Cousins
Gregg Tra ton
Jun Chen

February, 1992
(Revised August, 1992)
Contents

1 Introdu tion 1

2 Amendments 1

3 How a tool a esses the RTPT Support 2

4 Use of CL Pa kages 2

5 Naming onventions 3

6 Lisp data types 3

6.1 Strings : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 4

6.1.1 Spe ial strings : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 4

6.2 Date and Time : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 4

6.3 Enumerated types : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 4

6.4 Numbers : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5

6.4.1 Integers : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5

6.4.2 Real numbers : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5

7 Foundation data types 5

7.1 Set : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5

7.2 Sequen e : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 6

7.2.1 Polyline : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 6

i
 7.2.2 Other sequen es : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 6

7.3 Matri es : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 6

8 Foundation lasses 7

9 Foundation operations 8

9.1 Fet h All : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 9

9.2 Store All : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 9

9.3 Compute Dose Matrix : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 9

9.4 Compute Dose Points : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 10

10 VMP operations 11

ii
 1

1 Introdu tion

This do ument is a produ t of the Collaborative Working Group on Radiotherapy Treatment

Planning Tools [1℄. It is one of the do uments alled for by the Do umentation Task Group
[2℄. This do ument des ribes the Common Lisp language bindings for the programming
language independent Foundation Library and Virtual Ma hine Platform (VMP) that are
spe ied in [3℄, an earlier produ t of the Collaborative Working Group.

This do ument assumes familiarity with the software design model hosen by the Working
Group, as des ribed in the earlier reports [1, 2, 3℄. It also assumes some familiarity with
the Common Lisp programming language, in luding the Common Lisp Obje t System, as
des ribed in [4℄.

In this do ument CL is sometimes used as an abbreviation for Common Lisp, and CLOS
for the Common Lisp Obje t System.

Along with [3℄, this do ument provides information needed for two purposes. The rst pur-
pose is to write site-independent omponents of tools in the Common Lisp language, whi h
make use of the Foundation and VMP. The se ond purpose is to implement a Foundation
and VMP in the Common Lisp language. Those implementing a Foundation and VMP in
CL will need to make many more design de isions in addition to the ones spe ied here,
but this do ument gives suÆ ient information to guide implementation of a Foundation
and VMP in Lisp so that they will work with site-independent tool ode written by authors
a ording to the spe i ations given here.

In the rest of this do ument, the phrase \RTPT Support" will be used as a synonym for
\the Common Lisp implementation of the Foundation and VMP".

The RTPT Support annot ontain ode required for tool fun tions other than the opera-
tions expli itly alled for in [3℄. Support for fun tions other than those in [3℄ is not provided
by the lo al RTPT Support, but must be distributed with the site-independent omponents
of the tools.

2 Amendments

It may be ome ne essary to amend this do ument. The pro edure for amending the present
do ument is the same as des ribed in [2℄.
2 4 USE OF CL PACKAGES

3 How a tool a esses the RTPT Support

At ea h site, the RTPT Support will exist as one or more les of CL ode (whi h may either
be interpreted or ompiled, at the site's dis retion). These les must be loaded into the
lo al environment before a tool an use the RTPT Support.

One of the RTPT Support les must be named rtpt.*1, where the * after the . is some
string whi h is spe i to the Lisp produ t used at the site (.lsp for DEC VAX/VMS
Common Lisp, . l for Franz Allegro Common Lisp et .). It must be possible to load the
RTPT Support into the lo al enviroment by evaluating the Lisp form,

(load "rtpt")

This means that either the entire RTPT Support must be ontained in the single le named
rtpt.*, or the le rtpt.* must in lude forms that load the rest of the RTPT Support.

A site that distributes a tool written in Lisp must hoose some method for ensuring that
(load "rtpt") is evaluated before the tool attempts to use the RTPT Support. One way is
to in lude (load "rtpt") in the tool ode itself. Another way (whi h is more usual in the
Lisp ommunity) is to put (load "rtpt") in a separate (possibly site-spe i ) initialization
le whi h is exe uted in the lo al Lisp environment before invoking the tool. Whi hever
method is hosen must be des ribed in the do umentation that a ompanies the tool.

It is ne essary for CLOS to be loaded into the lo al Lisp environment before (load "rtpt")
an be su essfully performed. Some Common Lisp produ ts do not load CLOS automati-
ally when a Lisp session is begun, so at some sites it may be ne essary to arrange for this
to o ur.

Tools that use the CLX library for graphi output and user intera tion may also require that
CLX be loaded before the tool is invoked. If so, that must be des ribed in the do umentation
that a ompanies the tool.

4 Use of CL Pa kages

The names of the lasses and operations dened in [3℄ that are provided in the RTPT
Support must be symbols in a CL pa kage named rtpt. The RTPT Support must reate
1
In this do ument, fragments of CL language text and identiers used in CL language programs appear
in typewriter font.
 3

this pa kage. All of these names must be exported; that is, they are all external symbols.
No other symbols may be exported by the RTPT support. Tool writers may rely on the
fa t that the only symbols a essible in other pa kages than rtpt are the ones spe ied
here and in [3℄.

It is re ommended that tool ode always qualify ea h use of the names with the prex
rtpt:, instead of using use-pa kage or import. This will make it lear that the name
is dened in the RTPT Support. Implementors of the RTPT Support may use internal
symbols without fear of name lashes with site-independent tool ode.

Values of enumerated types, in luding status values returned by operations, must be symbols
in the CL keyword pa kage, as des ribed in se tion 6.3.

5 Naming onventions

The names of lasses, attributes and operations are given in [3℄ as one or more English
words with apitals and spa es. In the RTPT Support ea h name must be a ontiguous
sequen e of nonblank hara ters, the same hara ters as the names in [3℄ ex ept ea h series
of blanks must be repla ed by a single hyphen. Code may be written with the assumption
that symbol names are ase insensitive; this means that the lo al environment must not
alter the CL readtable to make it ase sensitive. In the Lisp programming ommunity it is
usual to type sour e ode in lower ase. Thus the operation name Fet h All in [3℄ be omes
fet h-all in CL.

If this simple naming onvention would determine a name that is already dened in [4℄, a
dierent name must be used. Therefore, the following subsitutions are ne essary:

Class name Attribute name CL name

Grid Values values grid-values

Blo k beam-blo k

6 Lisp data types

It is ne essary to spe ify whi h CL data types must be used to represent the values of
attributes (e.g. those things that are returned by the a essor fun tions). The spe i ations
are:
4 6 LISP DATA TYPES

6.1 Strings

The type text string in [3℄ orresponds to the CL type string.

6.1.1 Spe ial strings

Tools must use the strings "UNKNOWN" and "ABSENT" just as shown here (all upper ase) to
indi ate where string-valued attributes are unknown or absent. The name attribute of the
delivery referen e point must be "DRP"

6.2 Date and Time

The date and time in Image are represented by CL strings.

6.3 Enumerated types

Values of enumerated types dened in [3℄ must be symbols in the CL keyword pa kage. A
symbol that appears in CL ode that begins with a single olon : and whi h is not already
in the keyword pa kage will be reated and interned there automati ally.

The following enumerated types and their values are dened. Tool ode may use these
enumeration values, and depend on them being handled by the lo al Foundation implemen-
tation. For example, ea h site's implementation of the Fet h, Store and Compute operations
must a ommodate an :ele tron beam without \ rashing" (terminating abruptly without
an error message) or \hanging" (waiting indenitely, unresponsive to input); however, it is
not ne essary that the operations must return :su ess. Unless otherwise noted, Founda-
tion implementations may provide additional values not listed here (for example, a :neutron
beam modality), but tools must not depend on the existen e of those values, and must not
rash or hang if additional values are present.

 Modality in Beam Delivery System: :photon :ele tron

 Asymmetry dire tion in Combination Beam Delivery System, leaf dire tion in Multi-
leaf Beam Delivery System: :x :y (no other values are permitted).
 Image type in Image: : t :sim :port :drr
6.4 Numbers 5

 Status values for all Foundation operations: :su ess :failure

 Status values for ompute-dose-... Foundation operations: :unsupported-anatomy :unsupport

In addition, the values :absent and :unknown belong to every enumerated type.

6.4 Numbers

6.4.1 Integers

The type integer in [3℄ orresponds to the CL type integer. Relatively small integers
indi ating array dimensions and the ardinality of other small sets (as in n x samples et .
in Grid Geometry and n leaf pairs in Multileaf Beam Delivery System) may be assumed
to lie within the range of the CL type fixnum. However, large integers indi ating image
pixel values (range low and range high in Image and the elements of pixels in Image 2D and
voxels in Image 3D) may not be assumed to be instan es of CL fixnum.

6.4.2 Real numbers

The types real and real number (used inter hangably in [3℄) orrespond to the CL type
float. Tool ode must not depend on or require subtypes su h as short-float, et .

7 Foundation data types

7.1 Set

Attributes whi h are sets in [3℄ are represented as lists of instan es of the appropriate lass.
Examples of su h attributes are ontours: set of ontour in Volume, wedges: set of wedge
des ription in Beam Delivery System, and blo ks: set of blo k in Beam.
6 7 FOUNDATION DATA TYPES

7.2 Sequen e

7.2.1 Polyline

The x; y pairs used to represent verti es of polylines in [3℄ are represented by 2-element
lists, where ea h element is a CL float. The rst element of the list is the x- oordinate
and the se ond element is the y- oordinate.

The sequen e of verti es is represented by a CL list of su h pairs.

Note that list indexing in CL is zero-based; CL fun tions that take or return the integer
index (position) of list elements refer to the rst element in the list as element number 0.

7.2.2 Other sequen es

Other sequen es in [3℄ are also represented by CL lists. These in lude leaf positions in
Multileaf Beam Delivery System, orientations in Wedge Des ription and leaf settings in
Multileaf Beam. All of these are lists of oats.

7.3 Matri es

Matri es in [3℄ (4  4 transformation matri es, dose matri es, images) are represented by
CL arrays. Transformation matri es and dose matri es are arrays of oats and images are
arrays of integers.

CL array indexing is zero-based, so (for example) the indi es in transformation matri es

range over 0..3, not 1..4.

For transformation matri es, the rst dimension is the olumn and the se ond dimension
is the row. This means that in aref forms, the index that o urs rst is the olumn
index and the index that o urs se ond is the row index. For example, the tz element in a
transformation matrix transform (as dened in equation 2.1 in [3℄) is obtained by

(aref transform 2 3)

For dose matri es and image matri es, the index that o urs rst in aref forms is the z
 7

index, the se ond index is the y index, and the third index is the x index. So for images,
the order of indi es is plane, raster, pixel.

8 Foundation lasses

For ea h lass in [3℄, the RTPT Support must provide a def lass form. Tool authors must
use make-instan e to reate an instan e of a Foundation lass, as in

(make-instan e 'rtpt: ontour ... )

(In ode samples in this se tion, elipses \: : : " do not a tually o ur in the ode; they show
where ode has been omitted.) For every attribute, there is a keyword parameter a eptable
to make-instan e, whi h, if provided, sets the value of that attribute. The name of the
a essor fun tion is the attribute name given in [3℄, prexed by a olon to make it a keyword
(the name is subje t to the naming onvention given in se tion 5). Tool authors should not
use other te hniques for initializing obje ts, be ause the obje t internals are not known to
the tool authors.

For ea h attribute in ea h lass, the RTPT Support must provide an a essor fun tion.
The name of the a essor fun tion is the attribute name given in [3℄ (subje t to the naming
onvention in se tion 5). A tool author uses this fun tion to read the value of of an attribute,
as in:

(rtpt:verti es ... )

To write a new value for an attribute, the programmer uses setf with the same a essor
fun tion:

(setf (rtpt:verti es ... ) ... )

This do ument does not spe ify the a tual CL ode in the lass denitions; that is not ne es-
sary. There are many dierent ways to write denitions that omply with this spe i ation.
In parti ular, this do ument does not spe ify the slots in the lasses. It is not ne essary for
the slots to orrespond one-to-one with the attributes named in [3℄. A site's RTPT Support
8 9 FOUNDATION OPERATIONS

may in lude additional slots not spe ied in [3℄, and the values of the attributes spe ied
in [3℄ may be omputed from one or more slots by the a essor fun tions.

Tool authors must not assume that attributes are implemented by slots. Consequently, tool
authors annot use CL slot-value and (setf slot-value) to read and set attribute val-
ues, be ause the RTPT Support is not required to provide slots that orrespond exa tly to
attributes. For the same reason, RTPT Support implementors annot use the with-slots
ma ro or with-a essors ma ro to a ess attributes. Moreover, tool writers must not pro-
vide initialize-instan e methods for Foundation lasses, and must not provide a essor
methods for their attributes, be ause these would on i t with the methods provided in the
RTPT Support.

The simplest way to implement ea h lass in [3℄ is to use CL def lass to dene a CL lass
that in ludes one slot for ea h attribute in [3℄, as in the following example:

(def lass polyline ()

((verti es :a essor verti es ... )
(transform :a essor transform ...
... )

(def lass ontour (polyline)

... )

In this example, CLOS provides a default method for the a essors, so the RTPT Support
authors do not have to write one.

This sample is in luded for tutorial purposes only; it is not part of the RTPT Support
spe i ation. Many other implementation strategies are possible.

9 Foundation operations

The Foundation operations spe ied in [3℄ behave as CL fun tions. They may be imple-
mented as normal CL fun tions or as CLOS generi fun tions.

Obje ts passed to Foundation fun tions as input must have all attributes set to legitimate
values, and obje ts returned by Foundation fun tions must have all attributes set to legiti-
mate values. Status indi ators returned by Foundation fun tions must also have legitimate
values.
9.1 Fet h All 9

Status values returned by operations must be symbols in the CL keyword pa kage.

Operations are dened using a format similar to that used in [4℄.

9.1 Fet h All

fet h-all dataset-id lass-list [Fun tion ℄

Here dataset-id is a string, and lass-list is a list of symbols naming lasses (not a list of
lass obje ts). The RTPT support may bind values to these symbols. Tools may not modify
or depend on these values.

This fun tion returns two values. The rst is a list of instan es of all obje ts in the data set
spe ied by dataset-id, whose lass is one of those named by the symbol in lass-list. This
list may be nil, but must not in lude any invalid obje ts.

The se ond value is a status, one of the keyword symbols :su ess, :failure.

If no valid obje ts were obtained, the rst value returned is nil. In that ase, the returned
status value :su ess indi ates there were no obje ts available in the spe ied lass(es),
and :failure indi ates that something more seriously wrong happened, e.g., it was not
possible to nd the spe ied data set.

9.2 Store All

store-all dataset-id obje t-list [Fun tion ℄

Here dataset-id is a string, and obje t-list is a list of instan es of lasses dened in the rtpt
pa kage, whi h are to be written out to the named dataset. The obje ts are not required
to be segregated or ordered by lass.

This fun tion returns one value, a status, one of the keyword symbols :su ess, :failure.

9.3 Compute Dose Matrix

ompute-dose-matrix eld anatomy-solids anatomy-image dose-grid drp [Fun tion ℄

10 9 FOUNDATION OPERATIONS

Here eld is an instan e of Beam or one of its sub lasses. Ea h site's implementation is
expe ted to provide methods for all sub lasses of beam for whi h instan es exist at that
site. The eld parameter is pla ed rst, so this operation may be implemented as a generi
fun tion whose methods are sele ted based on the lass of eld.

Here anatomy-solids is a list of Solid, anatomy-image is an Image-3d, dose-grid is an instan e

of Grid Geometry, spe ifying where doses shall be al ulated, and drp is a list of three oats,
indi ating the x,y, and z omponents of the delivery referen e point.

An implementation may provide a dose al ulation method for either anatomy-image or

anatomy-solids or both. If a method is provided for only one ase, the operation should
return a status value as indi ated below if it is invoked with a value for anatomy that it
does not support.

This fun tion returns two values. The rst is the dose rate matrix, an instan e of grid-values
orresponding to dose-grid.

The se ond value is a status, a keyword symbol. The following values are dened:

:su ess | dose omputation su essfully ompleted.

:unsupported-anatomy | dose omputation method for this type of anatomy ( ontours

or image) not available at this site.

:unsupported-delivery-system | dose omputation method for this type of beam deliv-

ery system not available at this site.

:failure - other failures.

9.4 Compute Dose Points

ompute-dose-points eld anatomy-solids anatomy-image dose-points drp [Generi

fun tion ℄

Same as ompute-dose-matrix ex ept dose-points is a list of Point With Value.

This fun tion returns one value: status, a keyword symbol, whi h takes values as in ompute-dose-matrix.
In addition, this fun tion updates the value attribute of ea h element in dose-points with
the dose omputed for that point.
 11

10 VMP operations

The only VMP operation des ribed in [3℄ (other than those provided by the CL standard [4℄
and the CLX library) is Open.

There is no Lisp binding for the VMP Open operation. Instead, tools should use the
standard CL fun tion open or the standard CL ma ro with-open-file.

All fun tions required of VMP Open are provided by these standard CL onstru ts. For
example, in the CL fun tion open, the lename parameter orresponds to the le name pa-
rameter in [3℄ (CL provides fa ilities for dealing with le names, in luding dire tories, path-
names, et ., in an operating-system independent way, as des ribed in [4℄). Likewise, in CL
open, the keyword parameter :dire tion orresponds to operation in [3℄, :element-type
orresponds to le type, the stream returned by open orresponds to le variable, and
:if-exists and if-does-not-exist provide for the error handling that motivated the
in lusion of status.
12 REFERENCES

Referen es
[1℄ Ira J. Kalet, Edward Chaney, James Purdy, and Sandra Zink. Radiotherapy Treatment
Planning Tools First Year Progress Report. Te hni al Report 90{1, National Can er In-
stitute, Radiation Resear h Program, 6120 Exe utive Boulevard, Exe utive Plaza North,
Ro kville MD 20852, 1990.
[2℄ James Coggins, George Sherouse, Sharon Hummel, Jonathan Ja ky, Robert Drzymala,
and Martin Weinhous. Standards and Pra ti es of the Collaborative Working Group on
Radiotherapy Treatment Planning Tools. Te hni al Report 90{2, National Can er Insti-
tute, Radiation Resear h Program, 6120 Exe utive Boulevard, Exe utive Plaza North,
Ro kville MD 20852, 1990. Report of the Task Group on Do umentation of the Collab-
orative Working Group on Radiotherapy Treatment Planning Tools.
[3℄ Jonathan Ja ky, Martin Weinhous, James Coggins, Robert Drzymala, William Harms,
Sharon Kromhout-S hiro, George Sherouse, Gregg Tra ton, and Jonathan Unger. Foun-
dation Library Spe i ation and Virtual Ma hine Platform (VMP) Spe i ation. Te h-
ni al Report 91{1, National Can er Institute, Radiation Resear h Program, 6120 Ex-
e utive Boulevard, Exe utive Plaza North, Ro kville MD 20852, 1991. Report of the
Radiotherapy Treatment Planning Tools Spe i ation Task Group.
[4℄ Guy Steele, Jr. COMMON LISP, the Language. Digital Press, Burlington, Mas-
sa husetts, se ond edition, 1990.