Mercurial > cgi-bin > hgwebdir.cgi > POP > oldRepo

annotate 1__Development/6__Website/visualizer_project.html @ 0:a8cd65eca9a9

find changesets by author, revision, files, or words in the commit message
Initial add
author Me@portablequad
date Sun, 25 Dec 2011 14:39:36 -0800
parents
children
rev   line source
Me@0 1 <html>
Me@0 2 <head>
Me@0 3 <title>Untitled Document</title>
Me@0 4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
Me@0 5 </head>
Me@0 6
Me@0 7 <body bgcolor="#FFFFFF">
Me@0 8
Me@0 9 <h1>The Visualizer Project</h1>
Me@0 10 <p>&nbsp; </p>
Me@0 11 <p>This file describes the first Visualizer project </p>
Me@0 12 <p>========== </p>
Me@0 13 <p>Steps in the project</p>
Me@0 14 <p> It looks like a good way to go is to start with some simple examples, then
Me@0 15 work toward harder ones. This will be easier for you and at the same time let
Me@0 16 me develop the data structures over time, as the project proceeds. </p>
Me@0 17 <p>A good way to organize the project is to do a number of smaller, mini-projects.
Me@0 18 The first is just visualizing a syntax graph for "A + B", and having it paint
Me@0 19 in the Display. </p>
Me@0 20 <p>Please be aware that the syntax-graph data structures and the custom properties
Me@0 21 for EQNLang will change as more experience is gained in using them and it becomes
Me@0 22 clear that they have to be modified. This will cause the code you write to be
Me@0 23 modified, even after it is already working. </p>
Me@0 24 <p>========== </p>
Me@0 25 <p>Theory behind the syntax graph </p>
Me@0 26 <p>The theory behind the way I want to do the syntax graph will probably seem
Me@0 27 a bit "strange" to you at first, especially if you have any experience with
Me@0 28 compilers. It's a bit abstract; the reason is to allow the same data structures
Me@0 29 to be re-used for any CTOS language that can be designed. </p>
Me@0 30 <p>The best file to look at first is the "SyntacticElement.java" file, which has
Me@0 31 a very long comment that talks a bit about the thinking behind the data structures.
Me@0 32 </p>
Me@0 33 <p>To summarize the idea behind the syntax data structures: Syntax is a pattern
Me@0 34 that correlates to the visual pattern that humans look at. Each element of the
Me@0 35 visual pattern has a corresponding element in the syntactic pattern. </p>
Me@0 36 <p>So, that is the only thing that the data structures need to support: an element
Me@0 37 in the syntax for each visual cue. Visual cues are shapes and physical position.
Me@0 38 Physical position determines which visual pattern a given shape belongs to (more
Me@0 39 on this in the comment). </p>
Me@0 40 <p>So, there are only three kinds of thing in the syntax graph: </p>
Me@0 41 <p>Syntactic element </p>
Me@0 42 <p>Syntactic link </p>
Me@0 43 <p>Syntactic property </p>
Me@0 44 <p>plus, a set of property-types, and a set of property values, for links and
Me@0 45 elements </p>
Me@0 46 <p>To summarize the data structures.. I have only two main syntactic data types:
Me@0 47 elements and links. Each of these has a list of properties attached to it. </p>
Me@0 48 <p>The element properties state what kind of element it is (for EQNLang), such
Me@0 49 as a root of a syntactic pattern, and/or a structural element, and/or a shape
Me@0 50 containing element. </p>
Me@0 51 <p>The link properties state what kind of link it is (for EQNLang) such as a "back"
Me@0 52 link to the root of a syntactic pattern, or a link that indicates that data
Me@0 53 flows from one syntactic pattern to another..</p>
Me@0 54 <p> =========== </p>
Me@0 55 <p>Property Names and Property Values </p>
Me@0 56 <p>I have decided to make all property names and all property values be integers.
Me@0 57 I have included, in "EQNLangSyntaxSpecialization" a bunch of files that have
Me@0 58 static constants in them. These constants define the property names and property
Me@0 59 values. I also have a skeleton of how to use the properties in EQNLangSrcVisualizer.java
Me@0 60 </p>
Me@0 61 <p>That file shows how to use the constants inside switch statements. The switch
Me@0 62 statements steer, to code that takes some action on the DisplayList. Each piece
Me@0 63 of code is only invoked if some set of things is true. For example, the method
Me@0 64 "foobar" is called when "Currently processing a SyntacticElement, and it is
Me@0 65 a command-type" is true, and only when that is true.</p>
Me@0 66 <p> If you want to use a different code structure, write me an e-mail that makes
Me@0 67 a case for why you view the alternative structure as better. </p>
Me@0 68 <p>You will find in EQNLangSrcHolder a test syntax graph that has been built in
Me@0 69 the code. This is the first syntax graph that you will visualize. </p>
Me@0 70 <p>The next project after this one will add multiple syntactic patterns, positioning
Me@0 71 of them, and scaling of them. For now, just a single command with two variables.</p>
Me@0 72 <p> ============ </p>
Me@0 73 <p>What the Visualizer does</p>
Me@0 74 <p> Each command in EQNLang has not only a shape but "ports". Each port is either
Me@0 75 an input or an output. They are placed visually around the shape. </p>
Me@0 76 <p>The Visualizer must place an expression in the position of each port. If the
Me@0 77 input position in the syntax graph is empty, then the visualizer places an empty
Me@0 78 box in that input port's position. If the input position links to another command-rooted
Me@0 79 syntax pattern, then that entire syntax-pattern goes in the input-port's position.
Me@0 80 </p>
Me@0 81 <p>The plus command in "A + B" has both input ports filled, and the command has
Me@0 82 no explicit output port. By "no explicit output port" I mean that, upon evaluation,
Me@0 83 the expression will be replaced by whatever it evaluates to. An expression's
Me@0 84 visual placement implies where it's output goes to. Syntax patterns with implied
Me@0 85 output ports are placed inside the input ports of other syntax patterns. </p>
Me@0 86 <p>In the expression "A + B", the input ports of the "+" are filled by the "A"
Me@0 87 and "B". These are both "Name" patterns of memProcessor type. Name patterns
Me@0 88 have no visual input ports, and implied output ports. </p>
Me@0 89 <p>What this all means is that information is needed about the position of input
Me@0 90 ports for each command. This additional information is what the Visualizer will
Me@0 91 use to place the syntax-patterns. </p>
Me@0 92 <p>========== </p>
Me@0 93 <p>Details of the Visualizer project </p>
Me@0 94 <p>Here is what I would like (most of this is also in comments in the code): </p>
Me@0 95 <p>-- The Visualizer will generate a DisplayList, which is a linked list of DisplayElements.
Me@0 96 </p>
Me@0 97 <p>-- It first places a virtual shape for each syntactic element on a virtual
Me@0 98 grid, then generates a DisplayElement for each virtual shape. </p>
Me@0 99 <p>-- The Visualizer doesn't know what the actual shapes are, it only knows the
Me@0 100 name of the shape and a bounding box for it. The Visualizer works with the bounding
Me@0 101 boxes. </p>
Me@0 102 <p>-- The Visualizer places shapes onto a virtual grid. The grid is continuous,
Me@0 103 so each position is a float value. </p>
Me@0 104 <p>-- the Display will create its own version of the virtual grid, and set "0,0"
Me@0 105 of its virtual grid to the lower left corner of its window (to start with..
Me@0 106 the User can then pan and zoom). </p>
Me@0 107 <p>-- Each syntactic element has associated layout information that is looked
Me@0 108 up via some mechanism. </p>
Me@0 109 <p>-- The look-up info is loaded from disk during initialization of the Visualizer.
Me@0 110 </p>
Me@0 111 <p>-- The layout information is a shape plus a list of ports. </p>
Me@0 112 <p>-- The shape is a shape-name plus a bounding-box. </p>
Me@0 113 <p>-- a bounding box consists of an origin x,y value and width plus height value.</p>
Me@0 114 <p> -- The bounding box for a shape is the "minimum enclosing bounding box". The
Me@0 115 origin of the shape, when looked up, is always 0,0 </p>
Me@0 116 <p>-- a port has a bounding box too, but it has no shape.. instead, it's bounding
Me@0 117 box represents a constraint on how big the collection of shapes inside that
Me@0 118 port can grow. </p>
Me@0 119 <p>-- The origin of a port bounding box is relative to the origin of the shape's
Me@0 120 BB (bounding box). It's as if the shape defined its own mini-grid, and the ports
Me@0 121 are placed on the shape's mini-grid. Thus, the origins of the ports are actually
Me@0 122 offsets from the origin of the shape. </p>
Me@0 123 <p>-- The layout information for a "variable" in the syntax-graph comes from two
Me@0 124 sources: the type of variable is used to look up a font plus font-size, while
Me@0 125 the syntax-graph node has an attached text-string as a property-value. </p>
Me@0 126 <p>-- Generate the shape's bounding box by calculating it. First look up the bounding
Me@0 127 box for each character in the string (from information about the font). Then
Me@0 128 calculate the smallest bounding box that encloses the entire string. Make the
Me@0 129 origin of the calculated enclosing bounding box be 0,0. A variable has no ports,
Me@0 130 so done. </p>
Me@0 131 <p>-- do two passes when placing shapes. The first pass generates a tree of bounding
Me@0 132 boxes, the second pass scales and translates the bounding boxes, placing them
Me@0 133 onto the virtual grid. </p>
Me@0 134 <p>&nbsp;</p>
Me@0 135 <p>First pass: </p>
Me@0 136 <p>-- walk the syntax-graph (in a spanning tree fashion) and build up a tree of
Me@0 137 BoundingBoxTreeNode. </p>
Me@0 138 <p>-- start with a root BBChildLink. Set it to be the current BBChildLink. </p>
Me@0 139 <p>-- set the root of the syntax-graph to be the current syntactic element. </p>
Me@0 140 <p>-- Generate a BoundingBoxTreeNode for the current syntactic element. </p>
Me@0 141 <p>-- Set the link in the current parent BBChildLink to the newly created BoundingBoxTreeNode.
Me@0 142 </p>
Me@0 143 <p>-- look up the type of syntactic element to get its shape info and port list.
Me@0 144 </p>
Me@0 145 <p>-- If the syntactic element has ports, then make a BBChildLink for each port
Me@0 146 on the port-list. Make the BBChildLink's BB be the bounding box information
Me@0 147 that was in the port-info. This is a constraint bounding box. </p>
Me@0 148 <p>-- Each port corresponds to a child in the syntax graph, go to each child and
Me@0 149 make a BoundingBoxTreeNode, connect the corresponding BBChildLink to it, and
Me@0 150 repeat the above process. </p>
Me@0 151 <p>-- There are two kinds of bounding box here. One kind is the minimum size box
Me@0 152 that completely encloses a shape. The other kind is a constraint. When the second
Me@0 153 pass is performed, the shapes will be scaled, such that the shape bounding box
Me@0 154 gets as big as possible while still completely enclosed by some constraining
Me@0 155 bounding box. </p>
Me@0 156 <p>-- See the comments in the skeleton code for BoundingBoxTreeNode and BBChildLink.
Me@0 157 </p>
Me@0 158 <p>-- Once all the syntactic elements have been added to the bounding-box tree,
Me@0 159 go to the second pass, which performs scaling and translation of bounding boxes,
Me@0 160 which places them onto the virtual grid. </p>
Me@0 161 <p>&nbsp;</p>
Me@0 162 <p>Second pass: </p>
Me@0 163 <p>-- start with a default root bounding box that represents the entire graph.
Me@0 164 This is the "root" bounding box. It's origin is at 0,0 on the virtual grid.
Me@0 165 </p>
Me@0 166 <p>-- this root BB is made the parent constraining BB </p>
Me@0 167 <p>-- set the root node of the bounding-box tree as the current BoundingBoxTreeNode
Me@0 168 and begin: </p>
Me@0 169 <p>-- &lt;loop&gt;<loop point> </p>
Me@0 170 <p>-- generate the minimum enclosing bounding box for the BoundingBoxTreeNode's
Me@0 171 shape together with all of its child nodes. Leave the BoundingBoxTreeNode's
Me@0 172 shape where it is, so the generated enclosing BB will have its origin placed
Me@0 173 relative to the shape's origin, but possibly shifted due to the ports around
Me@0 174 the shape. </p>
Me@0 175 <p>-- calculate the scaling factor that will make the enclosing bounding box as
Me@0 176 large as possible while still being enclosed by the parent constraining bounding
Me@0 177 box. </p>
Me@0 178 <p>-- apply the scaling factor (which moves the origins, as well as changes the
Me@0 179 sizes of the BBs) </p>
Me@0 180 <p>-- calculate the translation to apply to the resized minimum enclosing BB to
Me@0 181 shift its origin to match the origin of the parent constraining BB </p>
Me@0 182 <p>-- apply that translation to the shape's enclosing bounding box and each of
Me@0 183 its children's constraining bounding boxes. Those bounding boxes are now at
Me@0 184 their final placement on the virtual grid, at their final size. </p>
Me@0 185 <p>-- generate the DisplayElement for the BoundingBoxTreeNode's shape, and add
Me@0 186 it to the DisplayList. </p>
Me@0 187 <p>-- now, repeat the process for the contents of each child constraining BB:
Me@0 188 In turn, set the child constraining BB to be the parent constraining BB.. and
Me@0 189 set the BBChildLink's node as the current BoundingBoxTreeNode.. and go to the
Me@0 190 <loop point> </p>
Me@0 191 <p>-- (Note, out of interest, that as one descends the bounding-box tree, the
Me@0 192 scaling factors multiply, and translations add..) </p>
Me@0 193 <p>&nbsp;</p>
Me@0 194 <p>-- When this process is complete for the entire syntax-graph, send the DisplayList
Me@0 195 to the Display.</p>
Me@0 196 </body>
Me@0 197 </html>