Follow this link for the latest version of the CD documentation.
cd was written by G. Edward Johnson at the National Institute of Standards and Technology. You may use this code for any purpose, but please give us credit. If find cd useful, please let us know. cd software produced by NIST, an agency of the U.S. government, is by statute not subject to copyright in the United States. Recipients of this software assume all responsibilities associated with its operation, modification and maintenance.
Some of this code is from the gd library written by Thomas Boutell. Mr. Boutell did not help with this project, so do not send him questions about cd. Code from gd is clearly marked in the source. Additionally, this document is patterned after the gd documentation, some portions have been copied verbatim. gd is covered by the following license.
gd 1.2 is copyright 1994, 1995, Quest Protein Database Center, Cold Spring Harbor Labs. Permission granted to copy and distribute this work provided that this notice remains intact. Credit for the library must be given to the Quest Protein Database Center, Cold Spring Harbor Labs, in all derived works. This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for Quest, not to interfere with your use of gd. If you have questions, ask. ("Derived works" includes all programs that utilize the library. Credit must be given in user-visible documentation.)
The Quest Protein Database Center is funded under Grant P41-RR02188 by the National Institutes of Health.
Thanks to Wolfgang Glunz Basically, everything is new, this is the first release. cd is a graphics library. It allows your code to quickly draw images complete with lines, arcs, rectangles, polygons, text, and multiple colors. most geometric shapes can be filled or have a hatch pattern as well. The output is a CGM file. If you are unsure of what CGM is, or if CGM is appropriate for your project, see the NIST CGM Homepage. Every effort has been made to ensure that the generated cgm files conform to the standard, however, if you do not use the library properly, you could generate invalid metafiles that no one is able to read, so be careful. To use cd, you will need an ANSI C compiler. Any full-ANSI-standard C compiler should be adequate, although those with PCs will need to replace the Makefile with one of their own. The cc compiler released with SunOS 4.1.3 is not an ANSI C compiler. Get gcc, which is freely available. See the Sun-related newsgroups for more information. You will also want a CGM viewer, if you do not already have one for your system, since you will need a good way to check the results of your work. You can fetch cd as a gzip‘ed tar file, or you can FTP it directly from zing.ncsl.nist.gov in the subdirectory cgm. Note: if you have a non-Unix system, you will need to acquire versions of "gunzip" and "tar" suitable for your system. Both have been ported to PC and Mac environments. Consult newsgroups relevant to your particular system. change to this directory and examine the Makefile, which you may need to change slightly depending on your installation (or more than slightly for a Windows or Mac environment). On UNIX systems the command "make all" will create the cd library and three example programs, cdsimple, cdtest, and color16. If you are using Borland Turbo C++ version 3 (or later I hope) try to make it using makefile.bor CGM files are always in Network Byte order, Big-Endian systems use this ordering. I wrote this on a Big-Endian machine, but it seems to work on Little-Endian‘s as well. I have Tested cd on Sun‘s, Ultrix, Linux, IRIX, and DOS (Borland). If you get it to run on other systems, drop me a note. cd lets you create CGM images on the fly. To use cd in your program, include the file cd.h, and link with the libcd.a library produced by "make libcd.a", under Unix. You will need to adapt the makefile for your needs if you are using a non-Unix operating system, but this is very straightforward. Look at the example programs included in this distribution for examples of using cd. The programs are cdsimple which is a heavily commented program that makes a small cgm. cdtest which makes a cgm with every different kind of shape you can use. It has lines, circles, arcs, ellipses, rectangles, polygons, and text as well as examples for setting the attributes for them. So look at it closely, it is your friend. The other example program, color16 allocates 16 colors using cdImageColor16 (these are the 16 standard Windows colors). Than it draws a rectangle with each of them. These programs are created automatically when you "make all". cdPointPtr is defined in cd.h, basically, it is an array of integer pairs p[m].x and p[m].y containing the x and y values respectively. pcnt is the number of points in this array (not the index of the last point, which is pcnt-1). pcnt must be at least 3 for polygons or 2 for polylines. Declare it with cdPointPtr is defined in cd.h, basically, it is two arrays of integers p[m].x and p[m].y containing the x and y values respectively. n is the number of points in this array (not the index of the last point, which is n-1). n must be at least 2 (otherwise you really don‘t have much of a line, it is closer to a point.) cdPointPtr is defined in cd.h, basically, it is two arrays of integers p[m].x and p[m].y containing the x and y values respectively. n is the number of points in this array (not the index of the last point, which is n-1). n must be at least 3 (otherwise you really don‘t have much of a polygon, it is closer to a line.) Things get more interesting if you use cdSetTextOrient with this function. A more exact definition of tpath is This function adds the Orientation to the metafile every time. It does not interpert an attribute value of -1 as no change like many functions do, although if you put in the same numbers it won‘t re-add it to the meta file. In the event that all cdMaxColors colors (256) have been allocated already, cdImageColorAllocate will return -1 to indicate failure, otherwise it will return the index into the color table allocated. (Note that most functions return 0 on failure, but 0 is a valid color table entry.) cdImageColorAllocate does not check for existing colors that match your request, you might want to use cdImageColorExact prior to calling this function to keep from defining multiple indexes with the same color. If color alocation fails, use cdImageColorClosest to find the nearest matching color. If no colors have yet been allocated in the image, gdImageColorClosest returns -1. This function is most useful as a backup method for choosing a drawing color when an image already contains cdMaxColors (256) colors and no more can be allocated. See cdImageColorExact for a method of locating exact matches only. CD was designed to be easy to use instead of gd (or with gd, if you want to be able to produce both). However, There are significate differences between the way CGM handles attributes versus the way gd does. In particular, gd requires you to put the line color in the function call to draw lines, CD does not, Color, like the other attributes only need to be set when they are changed. I recomend that you read over the documentation of both to see what the differences are, and make appropriate changes to your code. If you really want to make as few changes as possible to your code, I have provided two functions to help you. cdImageLine takes the same parameters as gdImageLine and will draw a solid line of the color specified. cdImageRectangle draws a hollow rectangle with solid edges of the color specified. I did this by drawing four lines, so it is not a true rectangle. Again, I recomend you use cdLine and cdRectangle instead of these, but they are there if you want them. When you contact us and let us know you are using cd, you help us justify the time spent in maintaining and improving it. So please let us know. If the results are publicly visible on the web, a URL is a wonderful thing to receive, but if it‘s not a publicly visible project, a simple note is just as welcome.
Version 1.0
What is cd?
What else do I need to use cd?
How do I get cd?
How do I build cd?
gunzip cd1.2.tar.gztar -xf cd1.2.tar
This will create the directory "cd1.2" beneath the current directory.cd basics: using cd in your program
Function and Type reference
Types
cdPoint points[pcnt] where pcnt is the upper limit of the number of points you wish to have. then fill it in with points[0].x = x0; points[0].y = y0; and the like. Image creation, destruction, and saving
Drawing Functions
Returns 1 for success, 0 for failure. cdLine is used to draw a line between two endpoints (x1,y1) and (x2,y2) This line is drawn using the attributes set by cdSetLineAttrib The attributes that may be set are Line Type, Line Width, or Line Color. The endpoints must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdPolyLine draws a line connecting all the points specified by cdPointPtr. n is the number of points in cdPointPtr, (not the index of the last point, which is n-1). This line is drawn using the attributes set by cdSetLineAttrib The attributes that may be set are Line Type, Line Width, or Line Color. Note that it uses line attributes not edge attributes for drawing the line. The endpoints must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdRectangle draws a line which has (x1,y1) as the upper left corner and (x2,y2) as the lower right corner. This rectangle is drawn using the attributes set by cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes not line attributes for drawing the perimeter of the rectangle. The Rectangle must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdCircle draws a circle which has center (cx, cy) and radius r. This circle is drawn using the attributes set by cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes not line attributes for drawing the perimeter of the Circle. The Circle must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdArc3Pt draws an arc specified by the given points. (sx,sy) is the start of the arc, (ix,iy) is the middle of the arc, and (ex,ey) is the end of the arc. This arc is drawn using the attributes set by cdSetLineAttrib The attributes that may be set are Line Type, Line Width, or Line Color. Note that it uses Line attributesfor drawing the perimiter of the arc, not Edge attributes like cdArc3PtClose. The Arc must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdArc3PtClose draws an arc specified by the given points. (sx,sy) is the start of the arc, (ix,iy) is the middle of the arc, and (ex,ey) is the end of the arc. The arc is closed base on cl. If cl is 0 then pie closure will be used, resulting in a pie shaped slice. if cl is 1 then cord closure will be used and a straight line will be drawn from one endpoint to the other. This arc is drawn using the attributes set by cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes for drawing the perimeter of the arc, not Line attributes like cdArc3Pt. The Arc must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdEllipse draws an ellipse specified by the given points. (cx,cy) is the center, (d1x,d1y) is the endpoint of the first conjugate diameter, (d2x, d2y) is the endpoint of the second conjugate diameter. I can‘t really explain this one, if you come up with a good description, mail me. This ellipse is drawn using the attributes set by cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes not line attributes for drawing the perimeter of the Ellipse. The Ellipse must be within the bounds of the picture.
Returns 1 for success, 0 for failure. cdPolygon draws a closed polygon connecting the points specified by cdPointPtr. n is the number of points in cdPointPtr, (not the index of the last point, which is n-1). This polygon is drawn using the attributes set by cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes not line attributes for drawing the perimeter of the polygon. The polygon must be within the bounds of the picture.Font and text-handling functions
Returns 1 for success, 0 for failure. cdText puts a string of text ts starting at position (x,y) The Text is drawn using the attributes set with cdSetTextAttrib. The attributes that may be set are: cdSetTextFont, cdSetTextColor, or cdSetTextHeight. The point where the text starts must be within the bounds of the picture.
Returns 1 for success, 0 for failure. sets the path of the text to tpath. tpath is an integer with one of the following values
These are all relative to the charater base vector and up vector. If you haven‘t changed them (with cdSetTextOrient then the direction of the text will be right to left for 0, left to right for 1, bottom to top for 2, and top to bottom for 3. Each individual letter will still be facing in the normal direction. If you want to rotate the text use cdSetTextOrient.
Returns 1 for success, 0 for failure. (xbase,ybase) is the run and the rise of the line that the text is written along. For regular text that is rotated, set xup = -ybase and yup = xbase. Setting it to something different will result in skewed text (which may be what you want.) Text written from bottom to top at a 90 degree angle would have the following parameters xup=-1, yup=0, xbase=0, ybase=1
Returns 1 for success, 0 for failure. Sets the font index to font. It is an index into the font table, the possible values are:
font must be one of these values or the function will fail. See cdSetTextAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. Sets the foreground color of text to color. This should be an integer which is an index into the color table that you have previously allocated. See cdSetTextAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. height is an integer for the height of the text you are displaying. Bigger numbers make larger text. The size of the text is dependent on the size of the picture. See cdSetTextAttrib for more information on this and related functions. Line, Edge, and Fill attributes
Returns 1 for success, 0 for failure. lntype is the line type which is an integer with possible values of:
lntype must be one of these values or the function will fail. See cdSetLineAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. lnwidth is an integer giving the width of lines. With an image of height Y with line width 1 the displayed width will be 1/Y%. As an example, if you image is x=5, y=10, and you set line width = 1, and draw a vertical line, the resulting line will cover 20% of horizontal area. (I think anyway). See cdSetLineAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. Sets the line color to lncolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetLineAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. Sets the style of the interior of filled area elements. instyle is the interior style which is an integer with possible values of:
instyle must be one of these values or the function will fail. So, basically, if you want an interior which is transparent and you can see what is underneath it, use "empty" otherwise fill it in with a hatch or solid color. See cdSetShapeFillAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. Sets the fill color to incolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetShapeFillAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. Sets the hatch pattern for the interior of filled-area elements to inhatch. The fill style must be set to hatch for this to have an effect. the value for inhatch is the hatch style, which is an integer with possible values of:
lntype must be one of these values or the function will fail. See cdSetShapeFillAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. edtype is the edge type which is an integer with possible values of:
edtype must be one of these values or the function will fail. See cdSetShapeEdgeAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. edwidth is an integer giving the width of the perimeter lines. With an image of height X with line width 1 the displayed width will be 1/X%. As an example, if you image is x=5, y=10, and you set line width = 1, and draw a vertical line, the resulting line will cover 20% of horizontal area. (I think anyway). See cdSetShapeEdgeAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. Sets the color of the perimeter lines to edcolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetShapeEdgeAttrib for more information on this and related functions.
Returns 1 for success, 0 for failure. edvis is an integer that can have one of the following values.
If you set the edge visibility to off (invisible edges) than you will not see the edges, regardless of what other edge attributes are set. The other attributes will still be set and turning the edge visibility to on will make edges using the current edge styles. See cdSetShapeEdgeAttrib for more information on this and related functions. Color handling functions
Constants
Using cd instead of gd
Please tell us you‘re using cd!
G. Edward Johnson
lorax@nist.gov
