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

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