Table of Contents

1. Why and How?

A question was posed in an Eagle newsgroup, asking if it would be possible to view EAGLE layouts in a 3D representation. This had not been possible so far. As I had vacations at this time, I decided to set to work. Of course the first problem was how to convert a 2D picture into three dimensions. Then POVRay came into my mind.

POVRay Open Source project had been around for more than 10 years. It is a raytracer which can be controlled by a kind of script language (SDL, Scene Description Language). It was perfect for the EAGLE 3D project. EAGLE can generate text files with the help of a User Language Program (ULP). This text file needs to contain the SDL commands to make the layouts glow in realistic 3-dimensional brilliance.

Additionally EAGLE does not know anything about measurements in the 3rd dimension. So it was necessary to generate a library which contains all sorts of models to be used with POVRay.

This documentation was translated by Richard Hammerl. I think he did it very well. But I have translated some parts myself, so there may be some errors in English grammar.

Matthias Weißer

2. What is Supplied And What We Need

Filename What is this
Eagle Files (Subdirectory /ulp)
3d40.ulp ULP for Eagle ⇐4.09r2
3d41.ulp ULP for Eagle >=4.1
3dfunc.ulp Some functions for 3d.ulp
3dpack.dat Package reference file
3dconf.dat Configuration file (empty)
3dlang(_x).dat Language file German (other language)
3dcol(_x).dat Color mapping file German (other language)
3d_cam.png Image for dialog
3d_ko.png Image for dialog
POV-Ray files (Subdirectory /povray)
cap.inc Macros capacitors
capwima.inc Macros WIMA capacitors
connector.inc Macros connectors
diode.inc Macros diodes
ic.inc Macros integrated circuits
qfp.inc Macros xQFP packages
resistor.inc Macros resistors
socket.inc Macros sockets for ICs
special.inc Macros which do not fit anywhere else
switch.inc Macros switches
transistor.inc Macros transistors
tools.inc Miscellaneous macros, declares etc.
user.inc User settings (empty)
tex_elko.png Texture for electrolytic capacitors
tex_elko_axial.png Texture for axial electrolytic capacitors
Sample files (Subdirectory /examples)
MoDsMega.brd Board file for making the example
MoDsMega.pov POV-Ray file, all options active (v1.01)
MoDsMega.png Generated out of MoDsMega.pov
MoDsMega.ini INI file for POV-Ray

There are some additional BRD files which show most of the parts models available for 3D representation. The additional image pack contains images of all available parts in Eagle3D.

Software Requirements:

You have to run 3d40.ulp for that version.
If you are still working with an Eagle 3.55 license you could use the current Freeware to generate POVRay files.
www.cadsoft.de
www.cadsoftusa.com

This version of Eagle is now the current release. You have to run 3d41.ulp for this version.

You need this software to generate the image from the .pov-File.
www.povray.org

3. Terms of Use

Free usage for personal and educational purposes. Companies which want to use it commercially, should contribute something to the parts libraries. Simply define a part of your choice in SDL and send it to me. I often work with digital electronics, so I am of course interested in real IC’s. Microprocessors, memories, displays, CPLDs and FPGAs are also welcome. Sometimes I am in need of a printed circuit board. Simply contact me. 3D models defined by any user are of course appreciated, so that I can add them to the library.

Distribution and usage of 3D libraries and the ULP in personal projects is allowed only by courtesy of the author. Copyright of provided models remains with the respective author.

4. Features

4.1 PCB

The board will be generated either as a “prism” (default) or as a “box”. The board outlines drawn in layer 20 should be closed polygons. Otherwise, very strange board outlines might be generated. In case of display problems you should select the square option in the startup dialog. Round outlines were supported in version 0.97 for the first time. You may use boards whose outlines are entirely drawn with wires or consist of a circle. The usage of arcs is only supported for Eagle 4.1.

4.2 Resistor Rings and Labeling

Discrete resistors with a user specified value will be automatically drawn with correct resistance band colors. Only 4 bands will be generated, however, with a fixed tolerance (5%, gold band). Also SMD resistors will be labeled with the correct combination of three numbers. The part value must have a certain format.

Permissible formats include:

These figures may have a varying number of digits, such as ‘12k’ or ‘470’. If this format does not match exactly, one can’t foresee the result of the routine calculating the corresponding colors/numbers. Other information, which will not be evaluated, could be added after the resistor’s value. This information should not be separated by the unique resistance code characters { ‘R’; ‘k’; ‘M’; ‘,’ and ‘.’}.

4.3 Multilayer Boards

The inner structure of a multilayer board will be visible, if the board itself is disabled and the thickness of board and copper is increased significantly. A thickness of about 30 mm for the board and 1 mm for copper is recommended for a 4 layer setup. If the PCB is used, all the inner copper layers are not displayed because you can’t see them. So they don’t have to be rendered and you will get a little bit more rendering speed.

4.4 Polygons

To display a polygon correctly you have to calculate it with RATSNEST before starting the ULP. Polygons will be constructed using lots of small boxes in POVRay. The width and number of them directly corresponds to the ‘width’ used for the polygon in EAGLE. Very small values can lead to enormous POVRay files (>100MB!). To process such a file POVRay needs lots of memory and lots (and I really mean lots) of time. Avoid using too fine a line width. As a rule: Not thinner than 0.1 mm. However, even a coarser width can result in enormous rendering times. As a rule of thumb one can assume that about 500 to 1000 objects will require 1 MB of working memory.

4.5 Unknown Parts

It can be quite useful to manually assign parts. Often there is a model in the library but no corresponding assignment. So you can assign a selectable model to an EAGLE device. This will be saved in a file named boardname.mpd, which can then be used in future runs.

If you want to change an assignment you may need to edit the file “3dusrpac.dat” to delete those assignments you want to undo or delete the file itself. This file may be allocated in the instalation directory o in other place (probably in Eagle instalation directory, under “program files”).

4.6 Holes

Drill holes (for vias, pads, and holes) will be shown as black cylinders by default. For a general overview there is nearly no difference from real holes. This option defines a starting drill diameter size, from which all holes will be drawn as real drills. The default and a very usable value is 2 mm. In case of a via, it can happen that tracks run into the drill hole. In most situations this can be suppressed, but under some conditions it can nevertheless happen. If a polygon is drawn over a via it will likewise be covered.

4.7 Modules

Each individual POVRay rendering file can also be used as an input module, for example, to build a complete system which can consist of several separate modules. For example, a complete PC motherboard with vertical device adapter modules. To use this feature, you have to switch the file which is be used as a module into the module mode. This happens by setting

#local use_file_as_inc = off;

to on. Now the file can be used as an .inc file. In the target file

#include “filename”

will be added directly before other .inc file entries. Running this macro, which has been defined in the module file and which contains the whole board with its macros, now adds the new module to it. The macro has the following parameters:

Offset on the x axis

Offset on the y axis

Offset on the z axis

Rotation around the x axis

Rotation around the y axis

Rotation around the z axis

The macro should be called at the end of the target file, or at least after all #declare, #include, and #local statements. The macro name can be seen at the end of the module file or can be determined from the name of the BRD file. The BRD filename, however will be slightly changed. All letters will be uppercase

4.8 Exclude Lists

You can use Exclude lists with Eagle3D to have alternate types of parts on the same PCB and have to do only one run of the ULP. An entry specifying such a list is for example:

#declare pack_R32=off;

Here, the part is placed after the “_” the device name as it is in Eagle. If this name contains special characters (”.”,”-”,” “,”$”) they are replaced by an “_”. A number at the beginning of the name is replaced with a “Z”. These changes are required because POVRay does not accept special characters within identifiers. A file containing a number of these entries can be included in POVRay with:

#include “exclude.ex”

4.9 Silkscreen

The layers which are used for the silkscreen can be entered within the starting dialog. If the layer-number is even the object will be placed on the bottom of the PCB. If the layer-number is odd the object will be placed on the top of the PCB.

4.10 Prefixes

Some packages can be used for more than one type of part. A typical example are the SMD-packages such as 0805 and 1206. Because of this, the packages {1210, 1206, 0805, 0603 and 0402} become prefixed with the first character of the name of that part and then the assignment is done. So a part called R12 and with the package 0805 will rendered as a resistor type R0805. On the other hand a part called C43 and with the package 0805 will be rendered as a type C0805 capacitor.

4.11 Animations

You can produce animations. To create an animation POVRay requires a camera path. This path is represented by a mathematical function (a so-called spline). This spline needs a minimum of three control points. These points are defined by text elements in a special layer (normal 230). The texts in this layer have to have a special format. This format consists of two numbers.

The first number is the sequence information. This means that in this sequence the points are used to create the spline. You have to use an integer.

The second number represents the height of the point over the surface of the PCB. This number could be a real number.

Such a text element could look like: 3 4.2 This means that this is the third point in the animation path and it is 4.2mm over the surface of the PCB. The viewpoint of the camera is normally located right before the camera in flight direction. It is also possible to add an additional viewpoint path. To do this simply add additional control points with a V as first character: e.g. V1 3.4. See the supplied modsmega.brd as an example on how to define these two paths.

POVRay needs an INI-File to create an animation. Such a file is written by Eagle3D when you supply a minimum of three animation points. The file will have the same name as the POVRay-file but with the extension ini instead of pov. If you pass this INI-file to POVRay a sequence of images will be generated. You can then convert this sequence into a video file with programs like VirtualDub. In addition you have to set the parameter

#declare global_anim = off;

in the POVRay file to on. The Parameter

#local global_anim_showcampath = no;

shows you the animation path. You should set this to off if you want to create the animation. On the tab Miscellaneous you can change the layer of the control points and the number of frames you would like to generate. In the supplied modsmega.brd are some control points.

4.12 Automatic package generation

You can create packages without any knowledge of the POVRay language with information added to your libraries. The quality of these created packages doesn’t reach that of the handmade ones but it is OK for a quick overview. To do this draw the outline of the package in an unused layer with wire. Then add a text element to this layer. This text element describes the height and the color of your generated case. You can also use multiple layers to add more detail to your case. You can see how to do this in the supplied eagle3D.lbr. Some examples of the text element and what it does:

A part which is 3 mm in height and has a pure red surface.

A part which is 4.3 mm in height and uses the Eagle3D texture col_silver.

A part which is 2.5 mm in height and uses a self defined POVRay texture.

5. Start Dialog Options

5.1 Global tab

Output parts

Output wires

Output pads and smds

Unknown parts will be displayed as a red cylinder.

If an unknown part is found, a dialog will be shown to select a package from the library (see 4.5).

If active, pins of discrete parts will be shortened to a few mm length.

Output silk screen

If you make a run with parts output (automatic and manual) then the assignment will be written into the POVRay-File and also into a <boardname>.mpd-File. You can use this assignment by selecting this option.

Output polyogns (see 4.4).

Holes will be shown as real through-hole elements. In case of a via, however, wires can cover it (see 4.6).

Holes will be shown as black dots on the board. Looks nearly like real ones (see 4.6).

Outputs three cylinder reference triad along the coordinate axes.

Outputs the board (see 4.1).

The board will be drawn as a simple rectangle.

The area around the board will be rendered with waves and clouds.

Generates cutouts in layer 20 in the board.

Set the destination filename. This name is saved in the configuration file.

The output path points to the directory where the BRD file is.

Language settings for screen dialogs

Write the POVRay file and end the ULP.

Write the POVRay file, but don’t end the ULP. Thus the existing dialog settings will be maintained for reruns in the current Eagle session.

5.2 Board tab

Thickness of the board material.

The thickness of copper on the board.

From this limit onward, holes will be shown as real. Smaller ones will become ‘pseudo-holes’.

From this diameter onward vias will be covered with solder stop laquer.

Rotates the board around the respective axis by the given value.

5.3 Camera tab

Here is the camera

Camera looks at this point

The ‘camera viewing cone angle’

5.4 Spot tab

Switch on the spot

Set the color

Well, the spot’s position

The spot’s target, if activated

It’s not a ‘wide’ beam, but a directed spot light which has a certain target (see above).

The opening angle of the full intensity light cone.

This angle has to be wider than the radius. If this is true, the intensity decreases from full cone to this angle continuously (gradually?).

The light source does not cast shadows, but illuminates the environment.

5.5 Silk Screen tab

The layers named in the textbox (Wire’s from Packages) are printed out as silk screen. (see 4.9)

The layers named in the textbox (Wire’s from Board) are printed out as silk screen. (see 4.9)

The layers named in the textbox (Text’s from Packages) are printed out as silk screen. (see 4.9)

The layers named in the textbox (Text’s from Board) are printed out as silk screen. (see 4.9)

5.6 Colors tab

Here you can define some color presets. They can be changed later in the POVRay file itself.

If you have selected “User defined” in the Color preset box you can select the colors here.

Save a new color with its name and RGB settings in 3dcol.inc. From now on it will be available in the Color selection dialog.

6. File Formats

.dat

To integrate a new model you have to define the macro first. The format should look like it is in the standard libraries. That is, for parts which exist in various sizes (ICs, capacitors...) you have to be define a basic macro where the referring parameters set the properties. There are already two powerful macros for SMD-ICs (QFP_GRND and IC_SMD_GRND). After generating a part you have to make it available in the allocation file. A line in 3dpack.dat contains fields which are separated by a colon.

Field index Field meaning Boolean
[00] EaglePackageName
[01] Output name X
[02] Output value X
[03] Define color bands X
[04] SMD offset (parts will be moved pcb_cuhight up/down) X
[05] LED options (The LED options dialog will be displayed) X
[06] Ready for sockets (see explanation) X
[07] Ask for height of crystals X
[08] Has part a macro (for example, SMD jumpers) X
[09] SMD resistor, Generate number combination X
[10] Socket macro
[11] Height of socket in 1/10mm
[12] Comments concerning socket
[13] Internal for administration purpose (not used at present)
[14] Correction angle (y axis) (package to macro)
[15] Offset for correction x
[16] Offset for correction y
[17] Offset for correction z
[18] Use Prefix from Part?
[19] Shunt on pinheader (a dialog will be displayed) X
[20] Logo selection dialog will be shown X
[21] Reserved[8]
[29] Bounding-Box Minimum
[30] Bounding-Box Maximum
[31] POV-Ray macro (macro name and a left parenthesis)
[32] Package comments (German)
[33] Package comments (English)

Only 1 or 0 are allowed here. If option [06] is active, a socket will be generated in addition to the package. Information about the socket can be taken from the fields [10], [11], and [12].The options for each package must exactly match the POVRay macro definition. Otherwise a faulty file will be generated. Anybody who wants to change anything in 3dpack.dat, should have a clear understanding of the text above. I have enough time to integrate new packages, but not enough to explain to everybody the details concerning rules of field assignment.

6.2 3dusrpac.dat

This file has the same format as 3dpack.dat and is used as an auxilliary allocation file. This file does not exist by default, but can be created for assigning user created libraries.

6.3 3dlang.dat and 3dlang_e.dat

These files contain all of the text strings used in screen dialogs in German and in English respectively. If someone is interested, he could translate each line in the file into yet another language and send it to me. I will then bind it into the ULP.

6.4 user.inc

This file contains settings which can be made in the POV-Ray file, like camera and so on (the lines with #declare in the beginning). Therefore simply copy the lines from the generated file into user.inc and make the settings as you like. The lines with #local can also be seen in user.inc. Therefore you have to replace #local with #declare. Afterwards, the options in the generated file have no further effect. They will be overridden by those in the user.inc

7. Installation

There is an installer for Windows. Simply start the EXE you downloaded and install it anywhere you like. After installation start 3d40.ulp (Eagle 4.0x) or 3d41.ulp (Eagle 4.1x) from <installdir>/ulp by selecting

  File->Run

in the board editor. When you then want to render the image you have to save the produced POV-files in <installdir>/povray. Otherwise you can tell POVRay where to search for the INC-files. How you can do that is described in chapter 9.1

You have to unpack the ZIP-file in any folder you like. After that the procedure is the same as for the windows version. Simply start the right ULP for your Eagle version and create the POVRay file.

* Download Location

You can download the Eagle3D binary from here

8. Settings in the POVRay File

You can define some settings in the POVRay file which will be generated by the 3d.ulp. These items will be discussed here.

Set this value “on” to use the file as an include file in another POVRay file. For example in order to generate a board from several modules. The board will be defined as a macro with 6 parameters. The name of the macro can be taken from

the POVRay file after the ‘spot’ lines.

“0” or “1” changes the resistor’s form.

Set this value set “0” and the resistor’s colors will be defined by the following lines. Set it to “1” for the color to be set randomly.

Influences the color of discrete resistors. The color-number table can be seen in the POVRay file.

Set to “on” displays the bottom side of the board.

Sets the axis which the board is rotated.

Switch on/off the rendered background ‘waves and clouds’.

Set the pin length of discrete parts.

Various color presets for board, pads, silk screen and so on can be set here.

Set “on” the pins of discrete parts will be shortened to the above given measure.

Easy definition of camera settings.

Rotate the board according to the given values.

Particular parts of the board can be switched off here.

Define the setting of the 4 light sources here.

Don’t change these values.

9. Remarks Concerning POVRay

9.1 INI file

The generated POVRay file does not contain the whole path leading to the INC files, but only the filename. The INC files have to be either in the same directory as the POVRay file is, or one has to return the search path to POVRay. This can be done by creating an INI file. Such an INI file has the following format (Windows path):

;path to Windows font directory 
Library_Path=C:\WINDOWS\Fonts
;path to INC files
Library_Path=C:\eagle3D\inc

;this is the target for generated images
;if this section is commented out, it will be written 
;into the POVRay file directory
Output_File_Name=c:\temp\povout\
;Format of the image file
Output_File_Type=S
;Type N for PNG
;Type S for standard system format (Windows BMP, Mac Pict ...)
;Type C for compressed Targa (RLE)
;TypeT for uncompressed Targa 
;Type P for Unix PPM

;Settings for animations
Initial_Frame = 1
Final_Frame = 1
Initial_Clock = 0.0
Final_Clock = 1.0

The main INI file can also be edited in POV-Ray by going to “Tools | Edit master POVRAY.INI”.

9.2 Font

For part lettering Courier Bold (courbd.ttf) will be used. If you would like to use another font, for example because it is not available on your system, you may change the font name

#declare besch_font = “courbd.ttf”

in tools.inc.

9.3 Coordinate system

This is the coordinate system used in POVRay. The rounded arrows show the respective rotation around the axis in positive direction (left hand system).

9.4 Creating your own parts

A tutorial to create your own parts has been made and can be found here

I can’t create complete instructions to build your own parts. The Goal goal of this chapter is to write a style guide showing you how to create macros that they can easily be integrated into Eagle3D. You should carefully consider the following points:

I will also take macros which don’t accomplish all the points above but it would be a lot easier for me to integrate macros into Eagle3D if they fulfill the points above.

10. Thanks and Contacts

My thanks to several individuals for their collaboration and help provided in Eagle3D development. Please contact me if I have inadvertently missed anyone.

These are, in project chronological order:
Andreas Fecht <info(replace with at)vetter-und-fecht.de>
Robert Eckelmann <dc6xs(replace with at)dc6xs.de>
Axel Rühl <axel.ruehl(replace with at)gmx.de>
Tino Böhme <boehme.t(replace with at)web.de>
Andreas Rebmann <A.Rebmann-Elektrotechnik(replace with at)t-online.de>
Klaus Schmidinger <kls(replace with at)cadsoft.de>
Ing. J.M. Rafetseder <aon.912412027(replace with at)aon.at>
Uwe Bonnes <bon(replace with at)elektron.ikp.physik.tu-darmstadt.de>
Tobias Müller <Tobias_Mueller(replace with at)twam.info>
Tobyas Hennig <Tobyas.Hennig(replace with at)t-online.de>
Ulrich Trettner <ulrich(replace with at)trettner.de>
Rudi Hofer <rudi.hofer(replace with at)t-online.de>
Falk Stricker <Falk.Stricker(replace with at)gmx.de>
Frank Albert <ich(replace with at)ossiostborn.de>
Uwe Lorenz <u.lorenz(replace with at)er-dresden.net>
A. Zihlmann <berti(replace with at)wueschomania.org>
Walter Mücke <hochberg3(replace with at)01019freenet.de>
Joseph Zeglinski <JAZeglinski(replace with at)rogers.com>
Nigel Eke <me(replace with at)nigel-eke.com>
Duane Clark <dclark(replace with at)akamail.com>
Tilmann Reh <tilmann.reh(replace with at)autometer.de>
Richard Hammerl <hotline(replace with at)cadsoft.de>
MOSES <iloff(replace with at)mosesele.de>
Christian Hostelet <c.hostelet(replace with at)wanadoo.fr>
Henry Nestler <henry.nestler(replace with at)nexgo.de>
Friedrich Bleikamp <fbleikamp(replace with at)web.de>
Jan Bartels <j.bartels(replace with at)arcor.de>
Willi Ring <willi.ring(replace with at)web.de>
Oliver Saal <osaal(replace with at)gmx.de>
Juraj Rojko <juraj(replace with at)rojko.cz>
Daniel Cardona <dancardona50(replace with at)hotmail.com>
Frantiek Burian <BuFran(replace with at)seznam.cz>
Michael <info(replace with at)elk-tronic.de>
Carsten Kögler <koegler(replace with at)ftz-leipzig.de>
hebel23 <hebel(replace with at)hebel23.de>
Björn Schrader <b.schrader(replace with at)gmx.de>
Bernd Karle <info(replace with at)bksoft.de>
Philippe Boucheny <philippe.boucheny(replace with at)free.fr>
Juan Romero Alvarado jromalv@hotmail.com

Contact:
Matthias Weißer
Albert-Schweitzer-Str. 29
D-78087 Mönchweiler
matthias@matwei.de
http://www.matwei.de

If you send me an email please include “[Eagle3D]” in the Subject line of the email. If you didn’t do this it is quite likely that the mail will be caught by my mailfilter. New parts, proposals and requests concerning the ULP and 3D libraries are always welcome. But I beg you to use the common compression mechanism to send files (jpg for images, png or gif for schematics and all this wrapped with zip). Downloading images in 1024×768 bmp format with ISDN is no fun at all. If sending such a huge amount of data (>2MB) is really unavoidable , please contact me first.

If there are any errors, please also send the corresponding BRD file or the file which causes the error. This helps me check it out.

Thank you for your understanding.

Appendix A: Change Log

0.90 (26.06.2002)

0.91 (30.06.2002)

0.92 (02.07.2002)

0.93 (11.07.2002)

0.94 (18.07.2002)

0.95 (28.07.2002)

0.96 (15.09.2002)

0.97 (02.01.2003)

0.98 (10.03.2003)

0.99 (16.04.2003)

1.00 (18.06.2003)

1.01 (17.10.2003)

1.02 (10.03.2004)

1.03 (29.05.2005)

1.04 (28.01.2006)

1.05 (27.11.2006)