Canvas Commander 1.1
Users' Manual

  1. Introduction

    Canvas Commander is a graphics tool for 3D objects, texts, graphs and stereoscopic imaging. Just a few commands in a script file can show various 3D things and/or image files, with or without anaglyph effects. Therefore it is useful for artists, scientists or engineers who want to produce 3D images, without being tired of mouse-clicking on other graphics tools.

    Canvas Commander can generate dots, lines, planes, texts and curved surfaces (all or parts of a sphere, cylinder or torus, for example) by several commands. Therefore you can create a scene where various 3D objects are shown, from simple ones to complicated structures including graphs. An image file can be displayed as the background, in the final image (the scene).

    The image can be created as an anaglyph (also called an stereogram) which makes you feel stereoscopic 3D reality when viewed by 2-color glasses (red for the left, cyan for the right eye generally). As well as two image files (taken as the left and right photos by your digital camera), the 3D objects also can be anaglyphed since Canvas Commander can internally take two "photos" of them in the virtual space.

    dwTerm 2.0 or higher is needed. It is a shareware where more than 20 commands in a script is not allowed, the anaglyph display is within 400x300 area and the main window has an ad area, without the full license. But it has neither period limit, nor personal/commercial usage limit.

  2. Installation

    1. System Requirements

      • CPU: Intel 80486 or higher

      • OS: Windows 95, Windows NT 4.0 or higher

    2. Install

      dwTerm should be installed. Refer to the next section. If it is installed, install Canvas Commander as follows.

      Canvas Commander is distributed as a compressed file, *.zip. Extract all of the files contained in it into a folder. From now on, let's call the folder "Canvas Commander folder" whether you name it so or not.

      You can run example files (*.dsc) in the folder, by double-clicking them or by dwTerm menus. The folder also has this manual (manual.htm), in which those example scripts are described to help you see how to write new scripts.

      You are strongly recommended to follow the final step of installation, without which your scripts can run only when they are in the folder: Move cnvscmd.dll into the system folder. You don't have to know where your system folder is. Use the dwTerm's [Setup]->[System Folder] menu to open the system folder and just drag&drop the file from the Canvas Commander folder to the sytem folder.

    3. dwTerm

      dwTerm provides a minimal user interface to a dll program, so that the programmer does not have to know how to make a window and can concentrate on programming the core of the program. Any programmer can easily make such "dwTerm DLLs", that can be loaded and run by dwTerm. Canvas Commander is one of them.

      Go to http://www.softbattery.net/dwterm to download and install dwTerm 2.0 or higher.

  3. Getting Started

    Running Canvas Commander is running dwTerm, having it load Canvas Commander (cnvscmd.dll) and interacting with the dll through dwTerm. After running dwTerm, use the [File]->[Load...] menu to find a dwTerm script (*.dsc) in Canvas Commander's folder and load it, in which the dll name and the commands to run on loading are specified. Instead, you can run the script just by double-clicking it. The dwTerm's main window has the output display window on which the application DLL (Canvas Commander) shows graphics, the edit box to receive commands, and the status bar to show text messages.

    As the first example, run a script "hybrid.dsc" provided in the Canvas Commander folder. The result is included in the following screenshot. Somewhat different? The screenshot shows an anaglyphed version of the script, which is obtained by a little modification as described in this chapter.

    The screenshot also includes other example scripts' results. The example scripts are described in this and the next chapters to help you understand the commands which are listed in the final section of each chapter to write your scripts.

    Now, let's start to learn the commands, by viewing the commands in hybrid.dsc which can be opened by the [File]->[Edit...] menu. The menu opens it by the system's notepad.exe or other editor you specify in the Option menu. After editing and saving the script you can reload it by the [File]->[Reload...] menu or the hot-key Ctrl+Alt+R (also variable by the Option menu), to see the new result. If you are accustomed to your IDE (you may be, usually if you are a C programmer for example), you may prefer registering *.dsc and dwTerm.exe on the IDE.

    1. Canvas

      The result shown by hybrid.dsc has a photo image as the background and 2 model-objects overwritten on it. If you want to feel 3D reality using your anaglyph glasses or to display only the photo or only the models, you should change the first command "canvas" or other commands in the script.

      The dwTerm script syntax is simple: The lines after the "dwTerm Script Commands" line, that begin with a non-blank character are the commands. Therefore you may make some lines to be filled with comments or sub-titles, by starting each line with a blank. Note also that there are indented commands in the example which are ineffective (i.e. to be ignored by dwTerm due to the blank). They are provided to describe various usages of commands and you can test them by deleting the blank to make them effective.

      The first two parameters of the canvas command specifies the width and the height of the display window (also called the "canvas") in pixels respectively. The other parameters are optional and this example hybrid.dsc has two kinds of usage where pictures and models can be displayed, with or without anaglyph. If you don't need modeling, use only the first 2 or 3 parameters. The 3rd parameter in the first ineffective canvas command, valued 29 in this case is for anaglyphing of pictures and will be described in the next section. The next paragraphs are about modeling.

      The 3rd (or the 4th in the anaglyph canvas) select one of the 2 ways of projection from the virtual 3D space onto the display window. "ortho" means the orthogonal projection (like CAD programs) and other string ("pers" in this case) means the perspective projection (far objects look small). The next 4 parameters are respectively the width, the height, the distances of the near and the far planes from the "camera", of a virtual box in the space to be projected. The box is symmetric with respect to the horizontal and the vertical axis of the camera, so that it is a right rectangular box for the orthogonal projection and is a frustum for the perspective projection. Objects outside the box cannot be seen.

      The camera is at the origin in the space, and directed to the -z direction. The z+ axis penetrates the center of the canvas and goes toward the user. The +x and the y+ axes are projected onto the lines starting from the center to the right and to the top in the canvas respectively. The unit or dimension is arbitray. For example, you can use 4, 3, 5, and 300 as the 4 parameters in this command example (and the corresponding scaling in the modeling commands) or any float numbers. Note that the height/width ratios of the box and the canvas should be the same if you don't want distortions.

      Let's anaglyph in this example by indenting the first canvas command and making the next line be an effective command (deleting the first blanks). Save the script and reload it to feel a 3D reality, where some pens in the vessel are closer to you than others, and the torus is closer than the vessel and the sphere, when viewed with anaglyph glasses. If you want to change the default color filters for anaglyph (red for the left and cyan for the right) or want to copy the canvas image into the clipboard, refer to the Display and Debugging chapter.

      The last 2 parameters in this canvas command determine the depths or the left to right separations of objects in anaglyph. In anaglyph, the objects "on" the canvas (the monitor screen) should have zero-separtion, those closer to the user should have negative separations and those deep into the screen should have positive ones (left image being left to the right image). zScreen the first of the two parameter specifies the distance of the zero-separation plane from the camera, and the last parameter is the absolute separation that the objects on the near plane shoud have. Adjust these two values to avoid too small or too large absolute values of separations. The user hardly feels 3D reality but just dazzling overlapped images when the objects' images are too separated, since the color filters of the user's glasses cannot be perfect.

      There are other sets of ineffective canvas and picture commands in the example, which produce larger (800x600) images. You can test them, but anaglyphing is confined within 400x300 without the full license of dwTerm.

    2. Pictures

      The "picture" commands in hybrid.dsc display one or two image files which are taken by a digital camera. You don't have to spend hard time in typing the long file path as the last parameter. Just drop a file into the command window. Then the path apears at the caret. You can copy it with the popup menu by right mouse button or ctrl+c to paste into the script editor. Use "abs" as the 5th parameter to tell the command that the last parameter is the absolute path of the file. Otherwise ("rel" for example), the path is a relative one, i.e. with respect to the script's folder.

      If the 1st parameter is "r", the image file becomes the "right" image. Otherwise the image is taken as the "left" one. Without anaglyphing, the right picture command is ignored. The two image files in this script example, pens-l.jpg and pens-r.jpg, were obtained with the horizontal distance of several centimeters between the camera positions for the two photos.

      The camera was handled just by hands, being careful only in the orientation. The horizontal separation and the vertical deviation of the two postions are not so important, since the positive values of 2nd and the 3rd parameters of a picture command move the image to the right and to the bottom respectively. Generally, the former is used to move the pictures' whole anaglyph horizontally by the same values for the two pictures, while the 3rd parameter of the canvas command (that was 29 in the previous section) is used to separate the two pictures apart symmetrically from each other.

      Recommended steps are as follows. Eliminate the vertical deviation by the 3rd parameter of the picture command. Then adjust the separation by the 3rd parameter of the canvas command. Moving the whole anaglyphed image by the 2nd and the 3rd parameters of the picture commands or magnifying by the 4th parameter should be done after or before these steps.

    3. Start and End of Modeling

      If you don't want the background photo in the example hybrid.dsc, make the picture commands ineffective, or make the line next to the "clear" command effective. The latter makes the virtual 3D space have the specified backgound color. A color value in modeling has three float numbers between 0 to 1.0, meaning RGB intensities respectively in that order. The clear command without the color parameters makes the space's background transparent so that the pictures become visible as in the previous section.

      Note that the clear command initializes the modeling and nothing in the virtual space is visible without the command. Making the command ineffective in our example show you only the pictures although the other modeling commands are effective, which is useful when you adjust the pictures first.

      Commmands to build objects, to turn on the light and to transform the coordinate system will be descibed in the next chapters. You are recommended to make all the picture commands ineffective, to keep the number of commands within the dwTerm trial license limit of 20 when you make other commands get effective.

      Be sure to run the "finish" command to end the modeling.

    4. Primary Reference
      Common Error Messages (on the status bar) "Error! Wrong number of tokens" Too many or too few tokens are in the command. Tokens are defined to be strings without a blank in the command, and therefore are the command name, and the parameters. "Error! No canvas" The canvas command should be run the first than any other. Otherwise, any other command or wrong command name cannot be run and this message appears. "Error! Modeling not begun" Any modeling command cannot be run and this message appears, if the canvas is not for modeling or the modeling is ended. Any wrong command name too shows this message in this case. "Error! A wrong token" Any wrong command name shows this message, except the cases described above where other messages are shown. //*********************************************************************** // Canvas //*********************************************************************** canvas w h canvas w h offsetPicture canvas w h pers/ortho width height zNear zFar canvas w h offsetPicture pers/ortho width height zNear zFar zScreen offsetModel get the display window (called also the "canvas") ready to display pictures and/or the 3D virtual(modeling) space, with or without anaglyphing. The 4 usages above sets the canvas for one picture, for two pictures with anaglyphing, for one picture and modeling, and for two pictures and modeling with anaglyphing, respectively in that order. Pictures act as the background for modeling and can be omitted. Only the pictures without modeling can be displayed in the 3th and the 4th usages. w, h the width and the height of the canvas respectively, in pixels. offsetPicture the distance to the right picture's center from the center of the canvas. That of the left canvas is the negative of this value. pers/ortho The projection of the "virtual box" in the virtual 3D space onto the canvas is orthogonal if this parameter is the string "ortho", and perspective otherwise. The virtual box is a 3D region symmetric with respect to the horizontal and the vertical axes of the "virtual camera" and objects outside this box is not visible. The box is rectangular for the orthogonal projection and is a frustum for the perspective projection, bounded by the near and the far planes perpendicular to the camera axis, and also bounded by the left, the right, the top and the bottom planes parallel to the axis. width, height the width and the height of the virtual box, viewed from the camera. Therefore they are measured in the near plane as the distances, between the left and the right planes, and between the the top and the bottom planes respectively, which are the same as those in the far plane if the projection is orthogonal. zNear, zFar the distances of the near and the far planes from the camera respectively. zScreen, offsetModel determine the objects' image separations in anaglyph as follows. zScreen is the distance of the plane from the camera where objects have zero-separations, and offsetModel is half the left to right separation that objects in the near plane should have. Messages "Error! Too large canvas" The command failed because the canvas is too large to be ready (Note that the canvas need a memory space comparable to a *.bmp file of that image size, or twice for anaglyph). //*********************************************************************** // Pictures //*********************************************************************** erase black/white paints all over the canvas black or white. This can be used before displaying pictures, to paste the marginal area outside pictures with height/width ratios different from that of the canvas. black/white If this parameter is "white" the canvas is painted white. Otherwise, the canvas is painted black. picture l/r x y m rel/abs file displays a picture file. l/r The picture is taken as the "right" image in anaglyph if this parameter is "r". The picture becomes the left image, otherwise. The left picture only is displayed for non-anaglyph canvas. x, y the horizontal and the vertical offset of the picture, in pixels, with the positive values pointing to the right and to the bottom, respectively. Zero offsets make the picture center coinside with the canvas center. Offsets get applied after the magnification is performed as below. m a float number specifying the magnification. 1 makes the picture fit into the canvas, 2 makes the center region of the picture file with the half width and the half height fit into the canvas, and so on. The height/width ratio of the picture file is conserved during this mapping from the original image in the file to the displayed picture. rel/abs The last parameter, file is the absolute path string of the picture file (C:\images\aaa.jpg, for example), if this parameter is "abs". The path is taken as a relative one, otherwise. For example, a relative path "bbb\ccc.jpg" means that the folder bbb is in the folder of the script. file the path to the picture file Messages "Warning: No right canvas" The command is ignored because it is for the right picture while the canvas is not for anaglyph. //*********************************************************************** // Start and End of Modeling //*********************************************************************** clear clear r g b initialize the modeling, by painting the background (the virtual space) of objects using the specified color. If no color, the background is tranparent, so that the pictures from image files can be seen as the background. r, g, b 0 to 1.0 RGB intensities of the color finish finishes the modeling.

  4. Space

    The previous chapter already defined the coordinate system of the virtual 3D space for modeling and the relation with the canvas. This chapter describes the light to make objects visible with colors, and the coordinate transformations needed to systematically construct large objects consisting of smaller objects.

    1. Light

      There is one light in the virtual space to light the objects. It is infinitely far from the origin, almost like the sun. The direction to the light from the origin is the +z axis, but can be changed by the "light" command. The coordinates specified in the command just define the direction, not the position. If the command has no coordinates, it just turns on the light.

      In the example script hybrid.dsc, make the command ineffective. Then the result shows the 2 objects with simply white colors without shading. The "color" command changes this "object color without light" from white. It applies to all the object commands after the command. But all the examples and their descriptions in this manual are not interested in this color, but in the colors under the light turned on.

      You can test how the objects look by varying the light direction in the light command. Let's turn to the next command which is ineffective, "ambient". Make it effective to see the result. The objects look brighter with the shading less severe. The RGB color specified to the command means how much the ambient reflects the light.

    2. Transformations

      There are 3 transformation commands, "move", "rotate", and "scale". If such a command runs, then the object commands after that command are based on the new transformed coordinate system. You cannot be confused if you assume you are the executive director of a movie. By a transformation, you sitting on the chair are transformed to construct objects. The camera director at the origin sees you moved, rotated and scaled(?!).

      Test the transformation commands in hybrid.dsc to see objects become bigger, smaller or rotated by modifying the parameters. The 3 parameters of the move and the scale commands are the distances and the scale factors along the xyz axes, respectively. The first parameter of the rotate command is the rotation angle in deg and the others define the axis of right-handed rotation.

      The "push" and the "pop" commands are useful since it memorizes the present coordinates system and update the system from the memory respectively. The memory is a LIFO (Last In First Out) or "stack" structure, so that you can modularize objects construction. In hybrid.dsc, the sphere is positioned and scaled without being affected by the torus rotation or scaling, due to the push before the torus transformations and the pop after the torus. Without the stack, you get full of headache in just moving the sphere to a location you want.

      hydrogen.dsc shows other example of modularization, where spherical atoms gather to make a molecule with cylinderical bondings. This molecule can be used to construct a large thing. This example is using notations "*", "**" and so on, to denote the levels in the tree of modularization.

    3. Space Reference
      //*********************************************************************** // Light //*********************************************************************** light light x y z turn on the light. x, y, z specifiy the direction of the light. The light is infinitely far from the origin and these coordinates define just the direction. The defaults are 0, 0, and 1.0 (the light is in the user eyes!). ambient r g b specifies the ambient intensity. The ambient's light comes from the light. Therefore this intensity is something like the reflectance. r, g, b 0 to 1.0 RGB intensities. The default is 0 each. //*********************************************************************** // Transformations //*********************************************************************** move x y z moves the coordinate system. x, y, z the distances along the xyz axes respectively. rotate angle x y z rotates the coordinate system. angle the rotation angle in deg. The rotation is right handed: When the thumb is the rotation axis (with direction), curling the other fingers point to the rotating direction by the positive angle values. x, y, z defines the rotation axis. scale mX mY mZ scales the coordinate system. mX, mY, mZ specifiy the scale factors of the xyz axes respectively. For example, 2.0 for mX means that a point with the x coordinate 8.5 in the new system has the x coordinate 17 in the old system. push saves the present coordinate system on the stack. pop reads and erases the top of the stack, and update the present system by it.

  5. Material

    In this chapter, commands to specify common properties of obects are introduced. Any object to be built by an object command after such a command will have the properties specified.

    1. Colors

      There are 3 kinds of colors that an object has, which sum into the displayed image. The corresponding commands are "diffuse", "shine" and "emit". The former two specify how much the object reflects the light, and the latter makes the object "emit" lights (like a lamp). Therefore the latter is not affected by the (external) light's direction or the ambient. But the light should be turned on, even for it.

      The reflection is irregular for the diffused component, and regular for the shiny component (like mirrors). The first parameter of the shine command specify the regularity. If it is small, the object becomes shiny to a wide range of directions and hardly looks like a mirror.

      Test these commands in hybrid.dsc by changing the parameters.

      The diffuse command's default is non-zero, which is important for some planes not to be invisible depending on the orientation and the light direction, so that you can less probably fail to find the objects.

    2. Orientations

      The orientations of objects' planes affect the colors, even for the diffused component, and severely for the shiny component, since they change the angles between the plane and directions to the user and to the light. Furthermore a plane has the back and the front faces. The back face has a weaker diffused component than specified and has no shiny component.

      While the object commands generate planes with the front and the back faces defined, the "in" command swaps the roles. The "out" command retores the original roles. If you make the in command effective in hybrid.dsc you can see the intensities of the inside and the outside of the objects are reversed. Other example circular.dsc is good to see the effect of the in command, where it is used to let the disk be the shiny cap of the two cylinders and to make the inner cylinder shiny to the center.

    3. Styles

      Test the wire and the dot commands in hybrid.dsc, to see the wire and the dot versions of the objects. The parameters specify the wire thickness and the dot size. The solid command restores the default state which draws filled planes.

    4. Material Reference
      //*********************************************************************** // Colors //*********************************************************************** color r g b specifies the object color which appears when the ligh is turned off. r, g, b 0 to 1.0 RGB intensities. The default is 0 each. diffuse r g b specifies the diffused color (reflectance). The same value is used for the direct and for the ambient light. r, g, b 0 to 1.0 RGB intensities. The default each is 0.2 for the ambient and 0.8 for the direct light. shine regularity r g b specifies the shiny color (regular reflectance). regularity 0 to 128 integer. The smaller, the wider range of shiny directions. The default is 0. r, g, b 0 to 1.0 RGB intensities. The default is 0 each. emit r g b make objects "emit lights", independent of the external sources. r, g, b 0 to 1.0 RGB intensities. The default is 0 each. //*********************************************************************** // Orientations //*********************************************************************** in reverses the back and the front surfaces of objects. out maintains the back and the front surfaces defined by objects. //*********************************************************************** // Styles //*********************************************************************** solid lets object commands draw filled planes. This is the default style. wire wire thickness let object commands draw only the edges of planes. thickness specifies the wire thickness, in pixels. The default is 1. dot dot size let object commands draw only the vertices of planes. size specifies the point size, in pixels. The default is 1.

  6. Objects

    The object commands build planes. Use these commands to construct objects with many various planes. Generally they are centered around the origin, and have edge sizes of about 1, so that you usually should use transformation commands to locate and orient them and to let them have specific sizes.

    1. Polygons and Disks

      The examples polygons.dsc demonstrates the "triad", the "quad" and the "polygon" commands. All these commands draw polygons in the x-y plane at z=0, so that generally you should transform these planes to let objects include them.

      Test the commands in the example lessening the number of (x,y) vertices. Then the polygon command will draw a polygon (triangle) even for 2 points. That is, these commands draw polygons with the origin as the first and the last vertices. The triad and the quad commands draw polygons even without any parameters since there are defined some defaults in those cases. Refer to the reference section.

      The "disk" command draws a pie or cicular disk of radius 1 with or without the center hole, centered at the origin in the z=0 plane. Test it in circular.dsc by changing parameters. The first two parameters are the hole radius (=0 if you don't want a hole) and the number of radial slices. That is, the disk consists of polygons, the number of which is the product of the radial and the angular number of slices.

      The last two parameters are the sweep angle of the pie and the number of angular slices. Therefore with the sweep of 360 deg you can use this command also to draw equilateral triangles, squares, pentagons and so on, not spending time in calculation of coordinates with the polygon commands.

      The angle convention in the objects commands is that the positive angle is defined to be clockwise when viewed over the z=0 plane with 0 deg at the +y axis. Check this convention in circular.dsc by trying +60 and -60 deg instead of 360. Wrong? Consider the rotation command used.

    2. Pipes, Horns and Cubes

      You don't have to spend tedious time in building all the bent planes with only the three polygon commands and transformations. The "pipe" and the "horn" commands build strips with rectangle and triangle faces respectively. Test these commands in pipe.dsc and horn.dsc, by lessening the number of the last pairs of parameters. They represent an open or a closed polygon in the z=0 plane, but what are drawn are the quads generated between the polygon and the moved copy of it in the pipe command, and are the triads generated between the polygon and a point in the horn command. The offset and the point are defined by the first three parameters.

      The commands without any vertex parameter use the default square as the polygon.

      If your pipes or horns have a discrete rotational symmetry, you may not use these commands but use other ones introduced in the the next section. The curved surfaces in those commands consists of flat faces, so that pipes with equilateral symmetric octagon cross-section are pieces of cake for example.

      The "cube" command demonstrated in cube.dsc can be used also when you make any right rectangluar closed box with the tree lengths different from each other, since you know what the scale command is.

    3. Curved Surfaces

      In circular.dsc, the "cylinder" command is introduced, which draws all or a part of a cylinder wall, with the z-axis being the axis of symmetry. One end of it lies in z=0 plane with radius 1, and the other in z=1 plane with the radius specified by the first parameter. The second parameter is the number of the slices along the z axis. The next two parameters are the sweep angle and the number of angular slices.

      Slicing a curved plane into many flat polygons is not sufficient for the plane to look smooth, and the cylinder command can make each polygon reflect incident lights like a smooth surface. This function is turned off if the last parameter in the command is the string "flat", and turned on otherwise ("round" in the example). You may use flat when you make a pipe with flat faces using this command instead of the pipe command.

      Try torus.dsc rather than hybrid.dsc, to test the "torus" command. The first parameter is the distance from the origin to the circular axis of the tube cross-sections of radius 1. The circular axis lies in the z=0 plane. The second 4 parameters specify the cross-section of the tube. If the section is assumed to be in the y-z (x=0) plane viewed from the +x axis, they specify the start and the end angles of the tube surface in the plane with the angle measured clockwise from the +z axis, the number of tube slices along the arc, and the smoothness (like the last parameter of the cylinder command) along the arc. The last 3 parameters are about the torus with respect to the z axis. They are the sweep angle, the number of angular slices and the smoothness.

      With 0 as the first parameter, the torus command can draw a sphere. But you may prefer the simpler "sphere" command, unless you need flat faces along the polar angle and round faces along the azimuthal angle or vice versa. Try sphere.dsc to make a sphere or a polyhedron.

    4. Texts, Dots and Lines

      saturn.dsc shows how to display texts, using the "text" command. The first 2 parameters define the location (x, y) of the text's center in units of its width and height. The front face of the text is at z=0, and the 3rd parameter is the text thickness. The other parameters define the text. For example, try "Saturn is a planet" instead of "Saturn".

      The commands hgrad and vgrad are used in graph.dsc, to graduate horizontally and vertically, respectively, in the z=0 plane. The parameters are the (r, g, b) color, the graduating-lines' length and the distance between any two adjacent lines. The number of the lines are determined by the number of the other parameters, which are the lines' names to be displayed at lines' ends and are usually numbers as in this example to act as the graduating-values.

      The example graph.dsc also uses 3 commands to draw dots and lines which visualize the graph data. The "dots" command draws dots using number-arrays created in advance by the "array" command. The latter allocates an array consisting of the numbers specified by the parameters, and the former displays dots located at (Xi, Yi, Zi) with X, Y and Z being the arrays created in that order. If there are 2 arrays only, Zi = 0. After drawing, the command deallocates all the arrays. The "line" command draws a line consisting of the segments from the first to the end points defined by arrays, and also destroys the arrays.

      Arrays can be read from files, written by you or by a program. The example graphf.dsc is the same as graph.dsc except that the arrays are created by "arrayf" instead of "array". In the example, arrayf reads the file named "table" and takes every 0-th or the 1st number per 3 numbers into the array.

      Although the "color" command is not very useful, the two example scripts uses it to make the number of commands be 20 the dwTerm trial license limit. If the "light" command is used early in the scripts as in the other examples, without the "color" command, you should use also the commands "emit 1 0 0" and "diffuse 0 0 0", since we generally don't want the graph data visualization changed by the light position and the default diffusion color is non-zero. In graph.dsc, the light command is used just before the hgrad and vgrad commands and there is no emit/diffuse command in between, since hgrad and vgrad internally runs the emit command for lines and the diffuse command for texts.

      graph2.dsc is the only one script example with more than 20 commands, and describes a graph with 2 sets of data. As in the screenshot below, the graph is rotated, which is useful when you want an artistic graph or when the data-sets are many enough for you to need a rotated view to adjust the sets and their names.

      In these graph examples, also note that the orthogonal projection is used in the canvas commands, for you to correctly compare the data with the graduating-lines, since the data dots and lines are closer to you than the graduating-lines are. You may use the perspective projection to get an artistic image. Anyway, you may use the orthogonal projection and do not rotate, when you compare a set with other sets and with the graduating-lines.

    5. Objects Reference
      //*********************************************************************** // Polygons and Disks //*********************************************************************** These commands draw polygon-shaped surfaces in the z=0 plane with the front side defined to point to the +z direction. A polygon begins at the origin as the first vetex and returns to the origin. The parameters xi and yi in the three commands triad, quad and polygon are the coordinates of the i-th vertex. When the parameters are insufficient in the triad and the quad commands, internal defaults are used. triad triad x3 y3 triad x2 y2 x3 y3 draw triangular surface. The defaults are (x2, y2) = (1, 0) and (x3, y3) = (0, 1). quad quad w h quad x3 y3 x4 y4 quad x2 y2 x3 y3 x4 y4 draw rectangular surface. The defaults are (x2, y2) = (1, 0), (x3, y3) = (1, 1), and (x4, y4) = (0, 1), except for the case of 2-parameters where the parameters specify the width and the height of the right rectangle so that (x2, y2) = (w, 0), (x3, y3) = (w, h), and (x4, y4) = (0, h). polygon x2 y2 x3 y3 ... draws a polygon. At least, 4 parameters are needed since a trinagle need 2 more vertices else than the origin. disk rHole n phi m draws a pie or a circular disk of radius 1 centered at the origin, with or without a center hole. The disk consists of n x m polygon slices which are quads except at the origin where they are triads. rHole the hole radius. It is Zero if no hole is needed. n the number of radial slices, from rHole to 1 phi the sweep angle of the pie. It is 360 for the full circular disk. The sweep starts at the +y axis and goes clockwise viewed from the +z space. m the number of angluar slices. //*********************************************************************** // Pipes, Horns and Cubes //*********************************************************************** cube builds a cube centered at (0.5, 0.5, 0.5), with edges of length 1 parallel to the xyz axes. The following two kinds of commands build pipes or horns on the z=0 plane. The origin and the last parameters define a polygon the same way as the polygon command, except that the polygon can be open. The polygon is not to be drawn and just specifies one open end of the pipe and the open end of the horn. The first 3 parameters define how the walls are built. Even only one vertex as the last parameters and the origin constructs a wall. The last vertex should be (0, 0) to make the polygon closed. Without a vertex parameter, the command uses the default polygon: a square by (0, 0), (1, 0), (1, 1) and (0, 1). The front sides of a wall is defined as follows. Let your right hand curl along the edge in the polygon. Then the thumb points to the direction that the front side is oriented. pipe x y z pipe x y z x2 y2 ... draw a pipe with rectangular walls made by the edges of the specified polygon and the corresponding edges of a new polygon obtained by adding shifts (x, y, z) to the former. horn x y z horn x y z x2 y2 ... draw a horn with triangular walls made by the edges of the specified polygon and a point (x, y, z). //*********************************************************************** // Curved Surfaces //*********************************************************************** These commands builds strips around the z axis with a discrete rotation symmetry consisting triads or quads. All have the parameter m, the number of (azimuth) angular slices. The cylinder and the torus commands have phi as the sweep angle the same way as in the disk command, while the sphere command does not have the parameter and use the default 360. sphere n phi m round/flat draws a sphere centered at the origin with radius 1. n the number of the polar angular slices, between the +z and -z axes. round/flat The command smooths the surface unless this is the string "flat". torus r theta1 theta2 n round/flat phi m round/flat draws a torus or its part, centered at the origin, with the circular axis of the tube lying in the z=0 plane. The cross-section of the tube has radius 1. r the radius of the circular axis of the tube theta1, theta2 the start and the end "polar" angles of the tube, from 0 to 360 deg, in a cross-section of the tube. The polar angle here is defined to be 0 at the +z axis and to increase clockwise when viewed from the +x space if we take the cross-section in the x=0 plane. n the number of the polar angular slices, between theta1 and theta2 round/flat The command smooths the surface unless this is the string "flat", along the polar angular line or along the azimuthal angular line according to whether the parameter is next to n or m respectively. cyliner rTop n phi m round/flat draws a cylinder wall or its part, with one end with radius 1 in the z=0 plane and with the other "top" end in the z=1 plane. rTop the radius of the top end n the number of the slices along the z axis round/flat The command smooths the surface unless this is the string "flat", along the angular line. //*********************************************************************** // Texts, Dots and Lines //*********************************************************************** text x y t Any strings ... display a 3D text of thickness t with its center at (x*width, y*height, 0). The system-default font is used, so that the width and height are determined according to it. The front and rear planes are at z = 0, -t respectively. hgrad/vgrad r g b L d n1 n2 ... draw vertical(hgrad) or horizontal(vgrad) parallel lines in the z=0 plane, of the same length L, with any line separated from the next by d, and of emission color r g b. Their names (n1, n2 ...) of diffusion color are displayed at the bottom(hgrad) or at the left(vgrad) ends of lines, and the number of them determines the number of lines. The names are any words, but usually are numbers, for the lines to be used as graduating-lines in a graph. array x0 x1 ... arrayf file n i create an array for the commands "dots" and "line". While "array" takes x0 x1 ... as the numbers in the array, "arrayf" read a text file with the path "file", in which numbers are separated from the next one by blanks or line-changes and every i-th (0-base) number per n numbers are taken into the array. Messages "Too many arrays" The command failed because there are already many arrays enough for the commands "dots" or "line". "Error in opening a file" The command failed because an error happened in openning a file. dots/line draw dots or a line. They use the points (Xi, Yi, Zi) or (Xi, Yi, 0) if 3 or 2 arrays are created respectively, where X, Y and Z are the arrays created in that order and i = 0, 1, ..., m-1 with m the arrays' minimum dimension. The dots are at the points. The line consists of the segments from the i-th to the (i+1)-th points for i = 0, 1, ... m-2. Note that each of the two commands destroys all the arrays, after drawing. Messages "Too few arrays" The command failed because there are too few arrays. "Empty array" The command failed because one of arrays has no members.

  7. Display and Debugging
    //*********************************************************************** // Display and Debugging //*********************************************************************** help lets your browser open this manual. copy copies the canvas (the display window) image to the clipboard, for you to use in other image editors. anaglyph r g b r g b changes the anaglyph colors to gray the left and the right images. You need this, unless your anaglyph glasses are the default type with red for the left eye and cyan for the right. The first 3 parameters specify the left color and the last ones specify the right color. For example, run "anaglyph 0 1 1 1 0 0" to just swap the default. stop stop str issues a modal box, right now for no parameter, or after a later command shows a message including the string specified by the str parameter. For example, if the parameter is "Error", scripting will stop after any command shows an error message, since all the error messages are "Error! ..." as listed in the reference sections so far in this manual. As stated in the box, the Yes button makes the scripting go on checking the next stop condition, the No button makes the scripting go on with the stop feature turned off, and the Cancel button stops the scripting with the feature turned off. This is useful to find which command is wrong in a script. See the status bar not only to see the message content but also the command number, when the script stops by the box. The message also appears in the title bar of the box.

  8. License Agreement

    Canvas Commander is Copyright(C) 2009-2011 http://www.softbattery.net.

    The compressed form of Canvas Commander, which is a file with "zip" extension and in which this file (manual.htm) is contained as one of the components, can be freely copied and distributed as far as it is not modified.

    A copy of the compressed form can be freely extracted into the component files to run cnvscmd.dll or scripts, or to read the manual. Any files except the scripts (*.dsc) are NOT permitted to be de-assembled, de-compiled, reverse-engineered, or modified.

    Canvas Commander is provided as is, without warranties of any kind. The copyright holder shall NOT be liable for damages of any kind.

  9. History

    • Version 1.1: Oct 26, 2011

      New 7 commands for dots, lines and texts are added, which can be combined to draw graphs: "line" and "dots" draw a series of line segments and dots. "array" and "arrayf" receive numbers and read a file to create arrays needed for "line" or "dots". "text" displays a 3D text. "hgrad" and "vgrad" draw graduating lines and texts.

      Some default values in this manual are corrected, or added if omitted in the previous version.

      The error message from the "picture" command is renamed as the warning message, since the right picture specified just gets ignored and the next commands runs.

      The description about the installation in this manual is modified.

      sphere.dsc has more slices than the previous version.

    • Version 1.0: Nov 25, 2009