updates

doc/Design_notes/index.html

@@ -20,7 +20,7 @@ Coordinate systems<br />
 <a href="Design_notes/modules/zmapFeature.shtml">Featuresets</a><br />
 <a href="Design_notes/notes/performance.shtml">Performance</a><br />
 <a href="Design_notes/modules/pipeServer.shtml">pipeServer Configuration</a><br />
-<a href="Design_notes/modules/zmapFeature.shtml">Styles</a><br>
+<a href="Design_notes/modules/zmapFeature.shtml">Styles</a> <a href="Design_notes/notes/glyph_style.shtml">and Glyphs</a><br>
 <a href="Design_notes/modules/zmapView.shtml">All about Views</a><br />
 
 WindowCanvasItems<br />

doc/Design_notes/modules/pipeServer.html

@@ -13,28 +13,42 @@ Scripts are to be installed locally with ZMap and the directory itself will be i
 </fieldset>
 
 <fieldset>
-<legend>Configuration - [ZMap] stanza</legend>
-In ZMap's main configuration file (~/.ZMap/ZMap, or as otherwise optioned) we specify each pipeServer and also set up a few other options as needed:
+<legend>Configuration</legend>
+(complete config documentation <a href="user_doc/configuration.shtml">here</a>).
+In ZMap's main configuration file (~/.ZMap/ZMap, or as otherwise optioned) we specify each pipeServer and also set up a few other options as needed.  This is driven from the ZMap stanza, and each source is specified in a stanza of its own:
 </p>
 <pre>
 [ZMap]
-# define the location for scripts
+# define the location for scripts and data
 # Of course these could be stored centrally somewhere if desired.
 # and pipeServers can use absoloute paths instead
-script-dir=/nfs/users/nfs_m/mh17/ZMap/scripts
+script-dir = /nfs/users/nfs_m/mh17/ZMap/scripts
+data-dir = /nfs/users/nfs_m/mh17/ZMap/scripts
 
 # Each data source must be referenced in [ZMap] by listing the source stanzas like this
-# Columns are displayed in the order given: in this example all the acedb features first then the 'other_feed' etc.
+# Columns are displayed in the order given:
+# in this example all the acedb features first then the 'other_feed' etc.
 # later in the ZMap file each source must be defined in its own stanza.
 sources = acedb ; other-feed ; yet_another_one
 
-# If styles are not defined via ACEDB the a file must be given in the ZMap stanza (not the source stanza) eg:
+# If styles are not defined via ACEDB the a file must be given in the
+# ZMap stanza (not the source stanza) eg:
 stylesfile = /nfs/users/nfs_m/mh17/zmap/styles/ZMap.b0250.file.styles
+
+[other-feed]
+# config options for 'other-feed'
+#
+
 </pre>
 <p>
 When configured, ZMap will request data from each source in parallel, hopefully speeding things up a lot. Each script will obtain and send the data 'somehow'.  They will replace the existing mechanism of Otterlace retreiving the data sequentially and adding to ACEDB on startup.
 </p>
-
+<p>Each source stanza has a 'delayed' option, whcih allows data to be requested on demand rather than at startup:
+<pre>
+# delayed == conect from X-Remote request, otherwise connect on startup
+delayed = true
+</pre>
+</p>
 </fieldset>
 <fieldset>
 <legend>URL interpretation</legend>

doc/Design_notes/modules/zmapFeature.html

@@ -151,7 +151,7 @@ There is a 'default bump mode' which is an attribute in its own right.
 <h3>Original method</h3>
 <p>This was done using GObjects and configuration files read in using GKeyFile functions.  A large number of parameters have been defined and access functions implemented, and this has become unwieldy.  Some complicated copy functions have been written to cope with data not explicitly defined by GObject parameters, most notably the 'is a parameter set' flags and the mode dependant parameters</p>
 <h3>March 2010 Implementation</h3>
-<p><b>I'm still working on this! Don't believe a word of it</b></p>
+
 <p>We still use GObjects but a number of aspects of the original implementation are changed:
 <ul>
 <li>The many interface functions have been kept - they are used extensively by acedbServer.c. They provide type checking and are therefore useful.

doc/Design_notes/modules/zmapServer.html

@@ -14,3 +14,20 @@ acedb/, DAS, and pipe/ are the servers that run in these threads.
 <p><a href="Design_notes/modules/zmapView.shtml#reqdata">zmapView</a> contains some notes about requesting data from pipeServer modules and other issues.</p>
 <p><a href="Design_notes/modules/pipeServer.shtml">pipeServer</a> details usage of that module.</p>
 </fieldset>
+
+<fieldset><legend>Servers and Threads</legend>
+<p>Traditionally with a single ACEDB server thsi will have been kept active with ZMap and ZMap would not run without it. With the advent of pipeServers being used to request data on demand it becomes necessary to have threads startup , run and then be cleared up,  a function that has been planned but not implemented.  There is code to kill off threads on shutdown, but the threads code does not include a clean exit!</p>
+<p>Tasks that need doing include:
+<ul>
+<li>documenting the threads/ slave/ server/ view interactions
+<li>implementing a clean shutdown in a slave thread / server
+<li>clearing up threads data cleanly
+<li>clearing up view-&gt;connection data
+</ul>
+</p>
+
+</fieldset>
+
+<fieldset><legend>Requesting data by coordinate</legend>
+<p> If unspecified a data source is requested to return data from coordinates 1 to N ie the whole sequence.  We need to be able to request data for a marked region or other subsets of this.  Currently start and end coordinates are included in requests to pipeServers, but this is opnly triggered from the ZMap coordinates given at startup.</p>
+</fieldset>
\ No newline at end of file

doc/Design_notes/notes/glyph_style.html

+<!-- $Id: glyph_style.html,v 1.1 2010-04-01 10:23:06 mh17 Exp $ -->
+<h2>Style definitions for Glyphs</h2>
+<fieldset><legend>Summarised</legend>
+<p>
+Click <a href="user_doc/styles.shtml">here</a> for a complete list of ZMap Style configuration options.
+As of april 2010 glyphs will be changed, the main differences being:
+<ul>
+<li>mode specific config options (eg 'alignment-incomplete-glyph') will be removed and replaced with generic commands that can be used in different style modes. 'glyph-type' can be used to specify the shape to be drawn
+<li>'glyph-mode' will be used to choose any particular processing that is needed eg to calculate whether to display it or not; this is mainly intended for sub-feature glyphs, but can also be used (eg) to choose to draw a vertical line in the column for 3-Frame slice sites.  Note that these modes have to be hard coded and therefore cannot be configured by styles.
+<li>variable sized glyphs driven by the style's score mode
+<li>alternate shapes or colour driven by a score threshold to select a different style
+</ul>
+Note that if we select 'mode = glyph' then the main styles options are used rather than the subfeature options - this is to allow frame specific colours etc to be set.
+</p>
+<p>
+Here's a summary of glyph configuration by way of examples.
+</p>
+<h3>Some relevant commands</h3>
+<pre>
+[my-style]
+mode = glyph                  # to display a feature as a glyph
+                              # this will apply the main styles config options to the glyphs
+
+[my-other-style]
+mode=alignment                # here glyphs are sub-features
+glyph-mode = 3-frame-splice homology non-concensus-splice truncated
+                              # selects type of glyph and code to run to drive the display
+glyph_type = shape            # shape to draw (both ends)
+glyph-3 = shape               # shape to draw (bottom end)
+glyph-5 = shape               # shape to draw (top end)
+
+score_mode = width height     # change size according to score
+score_mode = alt              # change colour or glyph shape according to threshold
+                              # there's no reason why width cannot be combined with alt
+threshold = X
+
+glyph-colours = pink          # for sub feature glyphs
+</pre>
+
+<h3>3-Frame splice site markers</h3>
+<pre>
+[3-frame-splice]
+
+mode = glyph                  # will use normal style parameters
+
+glyph_mode = 3-Frame-splice   # uses frame colour not main ones
+                              # has vertical line in middle of column
+frame_mode=only-1
+score-mode=width
+glyph-5 = dn-hook
+glyph-3 = up-hook
+colours = grey                # for central vertical line if we draw itfunctions
+frame0_colours = red
+frame1_colours = green
+frame2_colours = blue
+</pre>
+
+<h3>incomplete homology markers </h3>
+<pre>
+[align-xyz_a]
+mode = alignment
+
+glyph-mode = homology   # gets displayed according to calculations
+glyph-5 = up-tri
+glyph-3 = dn-tri
+glyph-score_mode = colour
+threshold = 5
+glyph-colour = red      # for >= threshold
+glyph-alt = align-xyz-b # complete other style for &lt; threshold
+                        # in this case just to change the colour
+</pre>
+
+<h3>non-conscensus splice site
+</h3>
+<pre>
+[align-abc]
+mode = alignment
+
+glyph-mode = non-concensus-splice   # gets displayed according to calculations
+glyph = diamond
+glyph-colour = blue
+</pre>
+
+<h3>Truncated transcript</h3>
+<pre>
+mode = transcript
+(TBD)
+glyph-5 = up-dotted-line
+glyph-3 = dn-dotted-line
+</pre>
+<p>
+This could be coded as a separate featureset in the transcripts column, in which case the style mode would be glyph.</p>
+</fieldset>
+
+<fieldset><legend>Defining glyph shapes</legend>
+<h3>Attempting Clarity</h3>
+<p>In order to make styles files readable by humans glyph shapes will be defined by names, which will refer to a config stanza in the ZMap main config file.  This will be called <b>[glyphs]</b> and will consist of a single line per glyph of the form 'name=drawing-spec'.
+</p>
+
+<h3>Specifying Glyph shapes</h3>
+<p>As we draw glyphs using GDK operations we will define shapes in a way compatible with these, and this means we can specify lines, simple polygons and ellipses.  We assume that only one filled polygon is to be specified per glyph in the interests of display speed.  The 'glyph-colours' command (or the normal style colours when the style mode = glyph) can be used to define the border and fill colours.
+</p>
+<p>Glyphs are defined via coordinates relative to an origin (0,0) specified in pixels. The origin is where the shape is anchored to the feature, and the feature's anchor point will be in the centre of its column at its Y-coordinate - it will be possible to define shapes offset from the centre.  Points are defined as (signed) coordinate pairs separated by whitespace.
+</p>
+<p>As the GDK drawing primitives draw filled shapes with border and fill colours if we attempt to combine these into one glyph we would end up with internal lines and opt not to allow this. (for example a square and a triangle combined)
+<pre>
+    _____
+   |     |\
+   |     | \
+   |     | /
+   |_____|/
+
+</pre>
+
+<h4>Drawing line based glyphs</h4>
+<p>We use angle brackets to enclose the glyph description.</p>
+<p>
+A list of points is given and by default lines between consecutive points are implied. Adding a '/' between points will signify a break.
+</p>
+<p>If the list of points is unbroken and the first and last points are identical then the stanza defines a polygon and the shape will be filled with the fill colour specified in the style.
+Note that 'polygon' has a very specific meaning in that it is topologically the same as a triangle – lines may not cross and there is only one fill region.  This means that a bow-tie polygon cannot be specified but things like triangles, stars, thunderbolts can.</p>
+<pre>
+[glyphs]
+up-triangle=<0,-4 4,0 -4,0 0,-4>          # 4th point to complete the loop and trigger internal fill
+up-walking-stick=<0,0 0,-8 -4,-8>
+truncated=<0,0 3,1 / 6,2 9,3 /  12,4 15,5>          # a sloping dashed line
+</pre>
+
+<h4>Circles Ellipses and Arcs</h4>
+<p>We use round brackets to delimit the description.</p>
+
+<p>Currenrtly ZMap implements only whole circles and we will extend this to allow ellipses and fractions of a circle.  To define a circular glyph we specify the bounding box with top left and bottom right coordinates, and then optionally a start and stop angle in degrees, 0/360 being at 3 o'clock (due to GDK), angles count up anticlockwise (due to GDK).
+It appears that ellipses can only be drawn as vertical or horizontal using GDK.
+<pre>
+[glyphs]
+circle=(-4,-4 4,4)                # a full circle
+horizontal-ellipse=(-2,-4 2,4)    # a flat ellipse
+lr-circle=(0,0 4,4)               # a small circle offset to below and right of the feature
+r-half-moon=(-4,-4 4,4 270 90)    # a half moon on the RHS
+</pre>
+</p>
+
+<h3>Re-sizing glyphs sized according to a feature's score</h3>
+<p>The points used to specify a glyph's size and shape correspond to the maximum size and when 'glyph-score-mode' is set as width or height then the pixel coordinates will be adjusted accordingly, subject to a minimum size of two pixels.
+</p>
+</fieldset>
+
+