The GNU 3DLDF Website

This copyright notice applies to the text and source code of this web site, and the graphics that appear on it. The software described in this text has its own copyright notice and license, which can be found in the distribution itself.

Permission is granted to copy, distribute, and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of this license is included in the file COPYING.TXT

An Importance Notice from the Author and Maintainer:

2006.04.09.

Since the beginning of January 2006, it has become much more difficult for me to find time to work on GNU 3DLDF. I've laid the groundwork for development in lots of directions, and I've got notebooks full of ideas for features that I'd like to implement. I hope that in the future I'll be able to work on GNU 3DLDF a lot. At present, I try to work on it whenever I can.

Under the circumstances, any support for the GNU 3DLDF project would be very welcome, especially regular employment for the author and maintainer. If you think you could help, please contact me for further information.

GNU 3DLDF would be ideally suited as the basis for projects in Computer Graphics and Animation at a college or university, or even for advanced high school students. If you are interested, please contact me.

Thank you.

Laurence Finston
Author and Maintainer of GNU 3DLDF

Introduction

GNU 3DLDF is a package for three-dimensional drawing with MetaPost output. GNU 3DLDF 1.2.0, the collective name for my development versions , implements an interpreter for a METAFONT-like language. GNU 3DLDF is intended, among other things, to provide a convenient way of creating 3D graphics for inclusion in TeX documents. It can also be used for creating animations, which can contain text typeset using TeX.

Late Breaking News

2006.11.09.
Added an image of a double-napped cone with shadow on the Cones webpage. The parser rules and functions needed for making it are new.

2006.11.08.
It is now possible to set, transform, and draw right circular and elliptical cylinders and cones. I'm still working on the functions and rules for the ‘cylinder’ and ‘cone’ types. I've added web pages for : Cylinders and Cones, but I haven't gotten around to putting any examples in them.

Old News

Sources

The complete sources for GNU 3DLDF are available from the CVS repository for the 3DLDF project on the GNU Project's software development site Savannah. The C++ program code is in the CWEB subdirectory.

CWEB Sources

I've written the C++ code using Donald Knuth and Silvio Levy's CWEB System of Structured Documentation. The files with the extension .web contain the C++ code for the main program. The files with the extension .w contain the GNU Bison code for the parser. Both kinds of files also contain documentation written using TeX .

If you want to get started reading the source code, the main() function is in main.web.

If you check the CWEB subdirectory, you will notice that it contains very few header files. These are generated from the .web files by ctangle, which is part of the CWEB package.

GNU 3DLDF is built incrementally. That is, the source files are ctangled and compiled in a particular order. As a consequence, the header files become available as the .web files are ctangled. loader.web is the first .web file to be ctangled and compiled. Of the header files belonging to the GNU 3DLDF package, it only includes config.h, which is generated by the configure script. pspglb.web is the next file to be processed, and includes loader.h. creatnew.web follows, and includes loader.h and pspglb.h. And so on. main.web is the last .web file to be ctangled and compiled, and includes all of the header files generated from the other .web files. The order in which the header files are included in main.web reflects the order in which the corresponding CWEB files are processed: loader.web, pspglb.web, creatnew.web, gsltmplt.web, io.web, colors.web, transfor.web, pens.web, etc.

Development Versions

2005.11.09.
Announcement: GNU 3DLDF Development Versions

I now strongly recommend that users use my development versions, collectively numbered 1.2.0.0, rather than Release 1.1.5.1. 1.2.0 is interactive, and therefore a lot easier and more fun to use than 1.1.5.1. I've also added a lot of features since I released 1.1.5.1. Click here for instructions on obtaining 1.2.0.0.

I'd like to release a new stable version of GNU 3DLDF, but I need to completely rewrite the manual. This is a very big job, and requires a large block of time for uninterrupted work—something I don't have at the moment.

While I'm well aware of how much better it would be if there was a manual, it is nonetheless possible to learn how to use 1.2.0 without one. The file sample0.ldf contains many examples of how to use 1.2.0.0, I've been adding explanations and examples to these webpages, and I'm very willing to answer questions addressed to the help-3dldf-*-AT-*-gnu.org mailing list. (Replace -*-AT-*- with @ for the email address.) Please note that you must subscribe in order to use this mailing list: In order to keep spam out, all posts from non-subscribers are automatically discarded. See Mailing lists for more information and instructions on subscribing. However, if you don't wish to subscribe, you may contact me directly.

A good source of information for the parser is the file parser.output. See the 3DLDF language page for more information. (I will be writing more there soon).

The development versions implement a language modelled on Donald Knuth's METAFONT and John Hobby's MetaPost languages, so it should seem familiar to users of those packages. For example, this is a simple but complete 3DLDF program:

beginfig(1);
point p[];
p0 := (2, 0, 10);
polyhedron d;
d := unit_dodecahedron rotated (15, 15, 15) scaled 5 shifted p0;
draw d;
dotlabel.top("$p_0$", p0);
endfig;
end;

I am making my development versions available on the CVS repository of the 3DLDF project on the GNU Savannah site.
I have taken steps to make it easier for people to download and install the package. The compressed archive file 3DLDFsnp.tar.gz in the SNAPSHOTS directory contains all the files needed to install the package. (You can also download it from another site by clicking on the filename. I try to ensure that the files are always synchronized.)
The file 3DLDFsnp.tar.gz.sig is a detached signature for 3DLDFsnp.tar.gz made using GnuPG (the GNU Privacy Guard). Alternatively, CVS users can download the entire repository from Savannah. Instructions for doing this can be found here.

Instructions for installing and using GNU 3DLDF can be found in the files INSTALL, 00README , and README in the CVS repository. I am currently in the process of updating these files, so if anything in them is confusing, or if you have any other questions, please don't hesitate to ask for assistance. I would prefer that queries be posted to the help-3dldf-*-AT-*-gnu.org mailing list. (Replace -*-AT-*- with @ for the email address.) Please note that you must subscribe in order to use this mailing list: In order to keep spam out, all posts from non-subscribers are automatically discarded. See Mailing lists for more information and instructions on subscribing. However, if you don't wish to subscribe, you may contact me directly.

I have started rewriting the 3DLDF User and Reference Manual to account for my changes. These files can be found here. The files are Texinfo input files, however readers should pretend for the present that they are plain text and ignore the markup, because it is not yet possible to generate output from them.

Distribution

2005.10.31.
I now strongly recommend that users use my development versions, collectively numbered 1.2.0.0, rather than Release 1.1.5.1. See Development Versions for more information.

In this release I correct a couple of minor problems I discovered in release 1.1.5:

The official site for downloading 3DLDF is http://ftp.gnu.org/gnu/3dldf , but I will continue to make it available here.

Documentation

2006.01.25.
The most recent version of the GNU 3DLDF manual (see below) documents Release 1.1.5.1. I need to rewrite it completely in order to account for the many changes I've made in my Development Versions. I have been documenting the latter on these web pages. The old manual may still be of use to people who want to know how 3DLDF is implemented, but it is quite out-of-date by now.

2005-01-22.
I've abandoned work on the GNU 3DLDF 1.2.0.0 Manual --- Plain Text Version (Last updated 2005-01-31). I now plan to convert it to Texinfo. Until I do, however, it may still be useful to people who want to learn how to use 3DLDF 1.2.0.0.

The downloadable versions of 3DLDF: The Program, and the versions in the distribution have the table of contents at the front. This is not the case, if you generate them yourself. In order to do this, I used dviselect and dviconcat. I have not yet written make rules to do have this done automatically.

User and Reference Manual

The 3DLDF User and Reference Manual , Edition 1.1.5.1 in HTML format, with one webpage per node, as a compressed archive file (gzipped tar file) for downloading.

The 3DLDF User and Reference Manual , Edition 1.1.5.1 in HTML format, entirely on one webpage, as a compressed (gzipped) file for downloading.

The 3DLDF User and Reference Manual , Edition 1.1.5.1, as a PDF (Portable Document Format) file for viewing on-line (if your browser has an appropriate plug-in).

The Program

3DLDF: The Program for version 1.1.5.1 as a PDF file for viewing on-line (if your browser has an appropriate plug-in).

3DLDF: The Program for version 1.1.5.1 as a compressed (gzipped) PDF file for downloading.

3DLDF: The Program for version 1.1.5.1 as a compressed (gzipped) PostScript file for downloading.

3DLDF: The Program for version 1.1.5.1 as a compressed (gzipped) DVI file for downloading.

Converting EPS Files

2005-09-02
The utility conveps is included in the GNU 3DLDF distribution. It is for converting the Encapsulated PostScript files generated by MetaPost to other formats.

When the EPS files generated by MetaPost don't contain any TeX text, there's no problem converting them to other formats, so there's no need for a special utility. However, when they do, programs that convert one graphics file format to another can't handle them.

conveps solves this problem by including the EPS files in TeX files, and running TeX, dvips, mogrify, and convert. The structured PostScript (PS) files produced by dvips namely can be converted to other formats.

The source code is available here: conveps.web conveps has quite a few options for manipulating the images in various ways. The cweaved output of conveps.web contains instructions on how to use it. The versions of this as of this date (2005.12.16) are contained in the following files:

conveps.pdf — PDF file.
conveps.ps.gz — Compressed (gzipped) PostScript file.
conveps.dvi.gz — Compressed (gzipped) DVI file.

Converting TeX Text to Images

It's sometimes useful to convert TeX text into other formats, so that it can be displayed in a browser or combined with images created in some other way. ImageMagick's convert program can be used to convert the PostScript files generated from TeX text to other formats.

The file box_math.txt contains TeX code for making examples of this. (It's called box_math.txt so browsers will display it as an ASCII, i.e., plain text, file without complaining.) The version of this file included in the 3DLDF distribution may be found here: box_math.tex. The latter file may be more recent than the version on this web page.

There are two basic ways of formatting text using the code in box_math.txt. The first way formats running text using a specified \hsize. In this case, TeX chooses the line breaks. The second way is for the user to specify the line breaks. In this case, the macro \boximage in box_math.txt chooses an \hsize large enough for the longest line.

In the following examples, the frames aren't part of the images. I've added them to show the size of the images.

It would be very tedious to type in the code for explicit line breaking for more than a couple of examples. Instead, the code in box_math.txt is intended to be used by a utility that generates images from TeX code and a few arguments for setting options.

The macro \boximage puts the text into a \vbox and surrounds it with a red frame made up of \vrules. The top, bottom, left, and right margins between the frame and the block of text can be set by the user. After running tex and dvips, a PNG file (b.png) is created from the resulting PostScript file (b.ps) by the command convert -crop 0x0 +antialias -fill white -opaque "rgb(255,0,0)" b.ps b.png. The -crop 0x0 option removes the parts of the image that lie outside the frame. The -fill and -opaque options together change the color of the red frame to white. The +antialias option disables use of anti-aliasing, so that the color of pixels in the image are left unchanged. Without this option, the -fill and -opaque wouldn't be able to remove the red frame cleanly, because some of the red pixels would have been changed. If a frame is desired, the -fill and -opaque options can be omitted. The first argument to \boximage makes it possible to specify a different color for the frame, if the image contains red text. The color used for the frame shouldn't appear in the image.

One problem with converting PostScript files created using TeX to images is the poor resolution and hence the poor appearance of such images when displayed in a browser. The relationship between image size and resolution is tricky. The fonts used for TeX are mostly available in small sizes for use on devices with relatively high resolution. Plain magnification doesn't produce good results, because single pixels are merely replaced by groups of pixels. I still have a lot to learn about the issues involved.

Another problem is that the images are not scalable in browsers. Increasing the display size of the text on a web page has no effect on the included images. It might be possible to have a set of images that are identical except for the font size and use JavaScript or PHP to choose the right one based on the magnification used for the web page. However, this would only work if JavaScript or PHP was enabled, and it might not be desirable to require this.

Mailing lists

2005-05-02. I've replaced @ with -*-AT-*- in all of the email addresses on these webpages, and removed all clickable references to email addresses. I've been forced to this step by the huge amounts of spam I receive.

2005-05-21.
I have reactivated the help-3dldf-*-AT-*-gnu.org mailing list, but only for subscribers. Postings from non-subscribers are automatically discarded. I have deactivated the other GNU 3DLDF mailing lists. I have been forced to take this step by the huge amounts of spam posted to these lists. For the same reason, I've also replaced @ with -*-AT-*- in all of the email addresses on these webpages, and removed all clickable references to email addresses. If would prefer that all queries and comments be addressed to help-3dldf-*-AT-*-gnu.org, but if you don't wish to subscribe, you may contact me directly.

2005-05-21. The following mailing list is now available:
(Replace -*-AT-*- with @ for the email address.)
help-3dldf-*-AT-*-gnu.org for users to ask one another for help.

To subscribe, visit http://lists.gnu.org/mailman/listinfo/help-3dldf.
Alternatively, you can send an email with subscribe <email address> as the subject or the body to
help-3dldf-request-*-AT-*-gnu.org.

File Permissions

I've now put the release versions of the files in 3DLDF under version control using RCS. This has significant advantages, but has the unpleasant effect of making some or all of the files in the distribution read-only, unless I've checked them out before calling make dist. On Unix-like systems, file permissions are changed using chmod. For example,
chmod u+w foo.web
makes foo.web writable for the user.

The dist target is generated automatically by Automake, and I don't know how to make it change the permissions to read-write. So users will have to reset the permissions themselves. Please let me know if you have problems: help-3dldf-*-AT-*-gnu.org (Replace -*-AT-*- with @ for the email address.) Please note that you must subscribe in order to use this mailing list: In order to keep spam out, all posts from non-subscribers are automatically discarded. See Mailing lists for more information and instructions on subscribing. However, if you don't wish to subscribe, you may contact me directly.

Reverting Buffers

The way GNU 3DLDF 1.1.5.1 and earlier versions using) are built makes it necessary to touch one or more of the CWEB source files sometimes, thus changing their datestamps. If you're currently working on one of these files, you will have to revert the buffer visiting that file. (If you're using 1.1.5.1, I strongly recommend switching to my Development Versions. You shouldn't be using any version earlier than 1.1.5.1.)

This will only affect you if you are editing the CWEB source files. It will not affect you if you are using GNU 3DLDF 1.2.0.0 or a more recent version. 1.2.0.0 is interactive, as will be any future versions, so that users will not need to edit the CWEB source files.

However, if you are affected by this problem, and you're using Emacs, you can set a key to revert the buffer without querying by putting the following s-expression (symbolic expression) into your .emacs file:

(global-set-key [f5] '(lambda () (interactive) (revert-buffer t t)))

Or, if you're using, for example, foo mode, you can put the following sexp into your foo-mode-hook declaration:

(local-set-key foo-mode-map [f5] '(lambda () (interactive) (revert-buffer t t)))

For example,

(setq lisp-mode-hook '(lambda () (local-set-key [f5] '(lambda () (interactive) (revert-buffer t t)))))

Or, if you've defined a foo mode yourself, you can put the key assignment into foo-mode-map:

(if foo-mode-map ()
(setq foo-mode-map (nconc (make-sparse-keymap) c-mode-map))
;; else
(define-key foo-mode-map [f5] '(lambda () (interactive) (revert-buffer t t))))

Links

Contact

If you want to contact me about 3DLDF, please put 3DLDF, 3dldf or something similar in the subject line of your email. Otherwise, it's likely to be filtered.

If you want to encrypt an email to me, you can use my public key .
Fingerprint: 0007 566D B0E0 96AE 3F4A EBE5 6213 D0F0 7376 08BA

Laurence Finston
Kreuzbergring 41
D-37075 Göttingen
Germany
email: lfinsto1-*-AT-*-gwdg.de
s246794-*-AT-*-stud.uni-goettingen.de
Please use only one address at a time! (Replace -*-AT-*- with @ for the email addresses.)

Top
An Important Notice
Introduction
Late Breaking News
Old News
The 3DLDF Language
Sources
	CWEB Sources
Development Versions
Distribution
Documentation
Conic Sections
	Circles
	Parabolæ
	Hyperbolæ
Polyhedra
	Cuboids
	Regular Platonic Polyhedra (Under Construction)
	Semi-Regular Archimedean Polyhedra (Under Construction)
		Great Rhombicosidodecahedron
Quadric Surfaces (Under Construction)
	Cones
	Cylinders (Under Construction)
	Ellipsoids
	Spheres
	Paraboloids (Under Construction)
		Elliptical Paraboloids (Under Construction)
		Hyperbolic Paraboloids (Under Construction)
	Hyperboloids (Under Construction)
		One-Sheet Hyperboloids (Under Construction)
		Two-Sheet Hyperboloids (Under Construction)
Wave Forms
Prime Numbers
Converting EPS Files
Converting TeX Text to Images
Graph Paper (Plain and Perspective)
Animation
Flipbooks
Manga Patterns (Screen Tone)
Code Samples and Images
Mailing lists
File Permissions
Reverting Buffers
Links
Contact