Configuring the Viewer

• A working build of the viewer
• A text editor you like, preferably with syntax highlighting for JavaScript and PHP (The one used in the example)

General Formatting

• The config files are found in the assets folder.
• Value Formats
  • Numbers in config.ini and shapes.txt:
    • Coordinates:
      • These are normally relative to the width specified in the window section.
      • So if the true viewer width = window width, all values will be their exact value as stated.
      • Normally the viewer will be set to scale to the screen size, the values in the config will scale with it
      • Even if the values scale, any coordinates going into or out of the viewer are relative to the width and height specified in the window section.
      • there are a few exceptions to this rule mentioned below.
    • Times:
      • These can be specified in milliseconds or seconds
      • If the number is greater than 5, the viewer assumes milliseconds, otherwise, it assumes seconds.
    • Special:
      • the value at: debug fakeTextureMax is a pixel count which is never scaled
  • Booleans:
    • Simple flags of true and false or t and f should work fine here, your preference
  • Colors:
    • These are specified in RGB or RGBA hex values with 1 or 2 digits of percision
    • If you need 2 digits of percision, color can be 6 or 8 digits long, RRGGBB, or RRGGBBAA
    • If you only need 1 digit of percision, color can be 3 or 4 digits long, RGB, or RGBA
    • FFF, FFFF, FFFFFF, and FFFFFFFF are all the same color (fully opaque)
• Drawing Order (from bottom to top)
  • image (Effected by Shaders)
    1. image slice
    2. shape defined in shapes.txt and invoked with viewerAddShapeToImage
  • UI (NOT effected by Shaders)
    3. shape defined in shapes.txt and invoked with viewerAddShapeToUI
    4. clicks
    5. highlights

config.ini

• The config.ini file is found in the assets folder.
• Value Formats
  • global:
    • fakeDensity: One of three ways to specify viewer dimensions. If this is true, the viewer will be scaled as if it were displayed on a 160dpi screen. Use this to specify a fixed physical size (like inches) for the viewer.
      • eg: if a dimension is 800px, the viewer will be 5 inches (inches × 160 = pixels)
      • This can not be used if you specify a custom width function in JavaScript.
    • overscan: Like an old TV, specify how much of the image to crop off on each edge
    • downscaleTexture: Not Recommended. If for some reason you do not want your slides to be chopped up into tinyer images on graphics cards which can't support the image size you provided.
      • This is a tiny bit faster than dividing up an image, but gerally produces unusable results.
      • If this is false, and the individual slice size is too large for the GPU, the viewer will first give every slice its own texture, and then downscale each one anyway.
      • You can call viewerGetTextureInfo() to see what all the viewer had to do to the image to get it to fit.
    • yield: The milliseconds the viewer can spend processing images before returning control to the browser. This is not an exact guarentee. The viewer processes an entire slide, and only checks yield time between each task. It is therefore almost guarenteed that the viewer will work longer than specified here. Firefox by default gives a script 10 seconds to yield control before telling the user it is slow. This is also the interval at which window.viewerListenerProcessing events are fired. The larger this value the faster the viewer will finish its work, but the progress updates will be less frequent. This only matters on older computers / mobile devices.
  • window:
    • height: The viewer height, if using fakeDensity or specifying a custom width with window.viewerStatsWidth() then this value won't represent the true viewer height, however, it is still used to specify the aspect ratio. All coordinates provided to and received from the viewer will have their y value expressed in relation to this value.
    • width: Same as height above.
    • barwidth: The scroll bar width (thickness).
    • barBorder: How much thicker the outside of the scroll bar is compared to barWidth
    • barColor: The color of the moving part of the scroll bar
    • borderColor: The color of the outer part of the scroll bar
  • click:
    • radius: The radius of the ring marking user clicks
    • thickness: The thickness of the ring marking user clicks, for a full circle, make thickness >= radius
    • depth: How many slides in each direction a click or highlight shows (depth of 0 only shows on the slide clicked)
    • color: The color of the click marker
    • highlightRadius: The radius of the ring marking highlights clicks
    • highlightThickness: The thickness of the ring marking highlights
    • highlightColor: The color of the highlight
    • overwriteLastClick: refers to viewerGetLastClick(), not click logging.
      • if true, viewerGetLastClick() will always return the last click.
      • if false, viewerGetLastClick() will return the first click after viewerResetLastClick(), any clicks after this click will be discarded.
  • record:
    • logScrolling: whether or not scroll logs are kept.
  • controls:
    • wheel: whether or not the scroll wheel is used to move through the image
    • scrollLimit: the max scroll magnitude per scroll.
      • Some systems (typically with trackpads) give enormous values per scroll. this caps them. Most systems don't have a magnitude greater than 1.
      • Custom client scroll limits can be set with viewerSetScrollLimit
    • scrollSensitivity: how sensitive each scroll is. A value of 1 will not augment the scroll value provided by the OS.
      • because slides have to progress in whole incriments, a fractional sensitivity will be stored until they make a whole value.
      • eg a value of 0.2 means the scroll wheel will click 4 times with no effect, then on the 5^th it will advance the slide.
      • a negative scroll value will invert the scroll wheel direction.
      • Custom client scroll sensitivity can be set with viewerSetScrollSensitivity
    • arrows: whether or not the arrow keys are used to move through the image
    • wasd: whether or not W and S are used to move through the image
    • holdTime: how long to hold a key for (in seconds) before it moves to the next slide.
    • drag: whether or not the image can be dragged with the mouse or touch screen to scroll through it.
    • dragDist: how far the image is drug before it is scrolled, note that this scales with the image by default, and is therefore not always the same physical distance.
  • debug:
    • quickKeys: whether or not to allow some keyboard keys to perform debugging actions, Basically, 'M' will cycle through images
    • fakeGPU: whether or not to fake the texture size below
    • fakeTextureMax: simulate a maximum texture size on a GPU (to force dividing up the image/scaling it)

slideDim.txt

• The slideDim.txt file is found in the assets folder.
• Meanings of each value (eg 4,3,8,8,64,t,.jpg), in order:
  1. 4 - The index for the set of slides (think: a specific trial), no other rows can have this same index. This can be between 1-20 (inclusive).
  2. 3 - The file number, for example, for file01, this would be 1. This can be between 1-20 (inclusive).
  3. 8 - The width, in slides.
  4. 8 - The height, in slides.
  5. 64 - The total number of slides NOT length × width (I realize in all of my examples these are the same number).
  6. t - A boolean value indicating whether you wish to record clicks on that trial (t or f are fine)
  7. .jpg - The file extension, (eg .jpg or .png) Case matters
• Important Considerations:
  • Every line flags an important image. Remove any lines for images you aren't using. Otherwise, the program will realize it didn't get an image it considered important, and signal a failure to load.
  • Reuse images wherever possible rather than copying in a new image. The images are never modified, clicks and windowing are applied at render time, so multiple trials can use the same image. For example, the reward page is indexed at 4 but reuses image 3. This might also be important if you are faking tumors with shapes. Reusing images decreases load and processing time.
  • No two lines should have the same index (first) number. That's silly.
  • Indices do not have to be in order, you can use only 1 and 20 if you are modifying a previous experiment (the demo only uses 1, 3, and 4).

shapes.txt

• The shapes.txt file is found in the assets folder.
• Meanings of each value (eg mark,30,30,4,8,t,ring,FFF), in order:
  1. mark - The name of the shape to use when it is invoked with viewerAddShapeToImage and viewerAddShapeToUI
  2. 30 - The height of the shape.
  3. 30 - The width, of the shape, height and width should be the same unless the shape is a square.
  4. 4 - The depth of the shape (how many slices in front and behind the image to show)
  5. 8 - The line thickness of the shape (only matters if the shape is a ring).
  6. t - A boolean value indicating whether or not the image fades as it scrolls further from the origin point (t or f are fine)
  7. ring - The shape of the … umm,… shape. This can be ring, circle, square.
  8. FFF - The color of the shape
• Important Considerations:
  1. square only referrs to the angles, it's actually a rectangle.
  2. but circle and ring can not be ellipsis at the moment.

Tutorial Videos