udpscope/help/C/org.udpscope.app/cursors.page

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="cursors">

  <info>
    <link type="guide" xref="index#analysis"/>
    <link type="seealso" xref="measurements"/>
    <desc>The shared vertical cursor pair and the per-row horizontal rulers, their four modes,
    and how a reading is formatted.</desc>
    <credit type="author copyright">
      <name>Martino Ferrari</name>
    </credit>
  </info>

  <title>Cursors</title>

  <p>Cursors read values off the traces. There are two kinds: one <em>shared vertical
  pair</em> that every row carries at the same time, and <em>horizontal rulers</em>, one pair
  per row, that belong to that row alone.</p>

  <section id="reach">
    <title>How to reach it</title>
    <steps>
      <item>
        <p>Press the cursors button in the header bar, or <key>c</key>. It switches the cursors on
        and off.</p>
      </item>
      <item>
        <p>The readings are in the dock (a read-only copy) and on the <gui>Cursors</gui> page, which
        <gui>Edit</gui> beside <gui>Cursors</gui> opens over the plot and which owns the mode
        and a <gui>Reset</gui> button. Drag a marker to move it.</p>
      </item>
      <item>
        <p>The mode dropdown offers four modes: <gui>vertical</gui> (the shared time pair),
        <gui>horizontal</gui> (the per-row rulers), <gui>both</gui>, and <gui>mix</gui>.</p>
      </item>
    </steps>
  </section>

  <section id="knowing">
    <title>Worth knowing</title>
    <list>
      <item><p>The vertical pair is <em>one</em> time for the whole figure, so moving it on
      any row moves it on all of them. That is what makes <code>dt</code> meaningful across
      rows.</p></item>
      <item><p>A ruler belongs to its row and nothing shares it, so two rows' rulers are
      independent. The plots of a split row are one row here: they share their y axis, so the
      rulers are at the same values in each.</p></item>
      <item><p><gui>mix</gui> is the reading mode: one line per <em>bound</em> trace, with the
      trace's own values at each marker and their difference. A slot with a name but no
      channel behind it is not a trace and gets no line.</p></item>
      <item><p>A value is the <em>nearest stored sample's</em>, never a number between two
      samples. Zoom in past the sample spacing and the line between two samples is something
      the plot drew, not data — so a reading off it would be the drawing. The hover crosshair
      reads the same way.</p></item>
      <item><p>Every reading carries a <em>metric prefix</em> so the digits sit in
      <code>1..999</code>: <code>10.52 mV</code>, not <code>0.01 V</code>. Two decimals is all
      an instrument landing on an <code>f32</code> sample can claim, so without the prefix a
      small value would read <code>0.00</code> and the reading would be gone. A stream that
      declares no unit gets the prefix anyway, written tight against the number
      (<code>585.24m</code>) — the space separates the number from its unit, and a spaced
      <code>m</code> with nothing after it would read as metres.</p></item>
      <item><p>A marker past the newest sample reads <code>--</code>. With only one marker
      over data the row reads <code>partial</code>: a difference between a number and nothing
      is not a number.</p></item>
      <item><p>In <gui>mix</gui> each marker also places a crossing annotation per trace,
      which is what lets you see on the plot which sample a number came from. It is <em>on
      that sample</em>, so when the marker falls between two it sits a little off its own
      line: the line is where you put the marker, the dot is the datum being quoted. The hover
      crosshair's mark snaps the same way, and is drawn larger than a trace's sample dots so
      it does not read as one more sample.</p></item>
      <item><p>The time row exists only in the modes that show the vertical pair.
      <gui>horizontal</gui> has no time row, by design.</p></item>
      <item><p>A cursor <em>stays where you put it</em> while a live view rolls under it,
      which is what a bench scope does: its <code>T0</code> is an age, so a marker left at
      <code>-1.5s</code> keeps reading the sample a second and a half old as the stream
      advances. A measurement's marks do the opposite — they travel with the sample they
      measured — because a cursor is a question you asked and a mark is an answer about one
      particular sample.</p></item>
    </list>
  </section>

  <section id="example">
    <title>Example</title>
    <p>Three traces in <gui>mix</gui> mode with both markers over data: 3 lines and 6 crossing
    marks, each line reading like <code>sine  0.31 V  -0.84 V  -1.15 V</code>. Move the second
    marker past the newest sample and the third column reads <code>--</code>.</p>
  </section>

</page>