3-D Circuits
The Circuit Animation Toolbox for MATLAB

To create your own animations, or to view the many animations that have been created by have not been put online yet, you need MATLAB version 5 or higher (Version 5.3 or higher is recommended for smoothest appearance), and a set of 23 matlab functions which constitute the Circuit Animation Toolbox, which is available, free of charge, below.

Creating animations requires familiarity with the basics MATLAB programming, but running the 22 ready-made animations, which are including in the zip file blow, is possible without learning MATLAB programming. See the instructions for running animations in MATLAB .

Users who wish to create their own animations should consult the instructions for creating new animations, below.

Download Circuit Animation Toolbox zip file (41k).

Download individual files (This is tedious, as there are about 50 files, and is recommended only if you cannot unpack zip files.)

Instructions for running animations in MATLAB

After downloading the files above and unzipping them,

Details of getting it running

Add the cani1.2 folder and its subfolders to the MATLAB path by choosing 'set path' from the file menu in MATLAB. 'Add with subfolders' is a convenient way to add both the 'caniFunctions' folder and the 'caniCircuits' sub-folders.
To get a list of the available animations, type 'help caniCircuits' in the MATLAB command window (at the '>>' prompt).
Many of these animations can be run simply by typing their names in the command window. However, others require input arguments. To find out about input arguments, type 'help <circuitname>' where <circuitname> is the name of the animation you are interested in. Then type its name with numerical values for each parameter, for example,
>>buckani(1,5,0.25)The 'save' option available for many circuits will substantially degrade the live display of the animation. Use it only to create a movie file to later convert to gif format for putting on the web, as described in the animations on the web instructions .
The circuit will be drawn in a figure window. Generally, you will be prompted to hit a key to start it running. You must do so in the command window, so you must first click on the command window and then hit a key. You may wish to shrink the command window and enlarge the figure window.
For notes on interpreting the images, see the notes in the animations on-line section.

Controlling it while it is running
While an animation is running, you may:
- Pause the animation temporarily by clicking and holding on the title bar of the figure window.
- Stop the animation by typing <ctrl>C in the command window.
- Rotate the view. In MATLAB 6, the 'rotate camera' option allows rotating the veiw while the animation continues. From the figure window 'tools' menu, select 'camera motion and 'rotate camera', or use the 'view' menu to display the 'camera toolbar.'
  In older versions of matlab, the 'rotate 3D' option under 'tools' or on the figure toolbar accomplishes the same thing, but without a live view as the figure is rotated.

Instructions for creating new animations

First check that you have downloaded the files and set them up on your path correctly, by testing an existing animation, as described above . In the instructions below, basic familiarity with MATLAB is assumed.

Simple Animations

Open the simple_example.m file in the 'CaniExamples' folder, and save a copy under the name of the animation you wish to create, in a directory of your choice on the MATLAB path. The file must have a .m suffix.
The function call aninit intializes some variables, such as the cell array structure that will contain handles to each of the graphics objects you create. You do not need to modify this.
Estimate the size of the grid of nodes you need to draw your circuit, and if necessary change the 'makegrid(3,3)' to larger dimensions. It is helpful to put a a grid with the node numbers as a comment, to refer to as you build the circuit. You can type showgrid(m,n) in the command window to display the same grid that is produced internally by a call to makegrid(m,n).
Now you are ready to build up the circuit by adding components one-by-one, with statements like
ca = addR(ca,1,2)This takes the circuit cell array ca and adds a resistor between nodes 1 and 2. The circuit is drawn in the Figure 1 window as it is built up by these commands. Elements available can be listed by typing 'help caniElements'. Simple elements are L, R, C, wire, V, I. See Advanced Features for details on diodes, switches and op-amps.
Current arrows can be added by ia = currentarrow(ia,n1,n2,cn)
This adds a current arrow to the circuit animation current-arrow cell array ia. The current number cn specifies which column in the current matrix (to be created below) is used to specify the current value. The arrow points from n1 to n2 when the current value is positive. Current numbers can be the same for more than one arrow if the currents are equal for each.
Now is a good time to try running your program and seeing if the circuit it draws is what you wanted. If current arrows are awkwardly positioned, you can move them to the other side of the element they track by reversing n1 and n2 for the current arrow; for current direction, you will now flip the sign from what you planned to use.
The number of frames, and a column vector of equally-spaced times are now specified. The units aad scaling the time vector can be arbitrary; the animation will be shown at a specified frame rate not in real time.
Calculate a voltage matrix vm that specifies the voltage at each node at each time. Each column corresponds to a node, and each row correponds to a frame in the animation, and the corresponding time in the time vector. The number of columns must match the number of nodes created by makgrid(n,m) (the product of n and m).
Calculate a current matrix im that specifies each current at each time. Each column corresponds to a current number in a currentarrow command, and each row correponds to a frame in the animation, and the corresponding time in the time vector.

The current and voltage matricies could also be imported from the output of a circuit simulator program; MATLAB commands to load that data (such as dlmread) would be used here.
Set the rate in frames per second. 20 normally gives good results.
Final setup is performed by the function call vm_scaled=aniset(vm) . This also automatically sets the scaling of voltages. cvm is the voltage matrix used to color nodes; it may be scaled differently, but is normally set equal to vm_scaled.
The final command needed is to run the animation with canimate(t,vm_scaled,cvm,im,ca,ia,rate,cvm);
Save your file.
Test your animation and debug as necessary. See above for instructions on running an animation .
When you have finished a good one, please email me a copy so I can put it in the collection including in the toolbox.

Advanced Features

Switches and diodes. Switches and diodes require an additional matrix swm, to specify whether they are on or off in each frame. The format works just like current arrows, with an extra number swn in each addD(n1,n2,swn) or addswitch(n1,n2,swn) function call, that specifies the column of swm to be used. The difference is that swm is a logical matrix of ones indicating when a switch is on and zeros indicating when it is off. Note that the ability to specify a diode as being on, even when the current through it is negative, is useful in illustrating reverse-recovery phenomena. The call to canimate must then include swm :
canimate(t,vm_scaled,cvm,im,ca,ia,rate,cvm,swm);
Opamps have three nodes, but they can't be positioned arbitrarily; the lead wires are in a fixed arrangement. See help on addopamp for details.
Looping. Looping to illustrate behavior of a periodic circuit is possible simply by putting the canimate command in a loop. In this case, it is desirable to avoid the intial pause that is the default. This is done by setting the optional argument skippause to one. For example, this code runs an animation
View angle. Although manual rotation of the camera angle is always possible after starting the animation, it can be helpful to put a good starting angle into your m-file. The standard matlab command view(az,el) sets the azimuth and elevation of the view.
Input parameters can be added to vary component values, etc. by making your m-file into a function with input parameters.
Changing the vertical scale is sometimes useful for making things easier to look at. You can fool aniset into using a larger scale by scaling its input up, and then scaling it back down afterwards , as in this example:

vm_scaled=aniset(vm*2); %Set up scaling on the graph, etc., scaled up by a factor of 2. cvm=vm_scaled; %Use full range for color scale. vm_scaled=vm_scaled/2; %Scale back down so that the voltage displayed is as in the original vm.
Saving an animation for web viewing is a topic addressed on a separate page .

Back to 3D circuits homepage , or jump to animations on-line , or to background information .

Thayer School of Engineering , Dartmouth College

For comments or questions email: Charles.R.Sullivan@dartmouth.edu

3-D Circuits The Circuit Animation Toolbox for MATLAB

Download Circuit Animation Toolbox zip file (41k). Download individual files (This is tedious, as there are about 50 files, and is recommended only if you cannot unpack zip files.)