Fix #1629 by not reallocating DecodeSegments
[pulseview.git] / manual / analysis.txt
1 == Data Analysis
2
3 Once you have acquired some measurement data, it's time to have a look and see what
4 insights you can gain from it. Usually, the first step is to look at the data as a
5 whole, achieved by clicking the _Zoom to Fit_ button:
6
7 image::pv_analysis.png[]
8
9 <1> Zoom-to-Fit button
10 <2> Zoom in/zoom out buttons
11 <3> Cursors
12 <4> Time scale (used to set up and show markers, see below)
13
14 If you have located an area of interest (maybe with the help of decoders, more about
15 that later), you can zoom in on it using the _zoom in_/_zoom out_ buttons, using the
16 scroll wheel of your mouse or the pinch/expand gestures on your touch panel.
17
18 [NOTE]
19 When a data capture is ongoing, the Zoom-to-Fit button stays active if you click it,
20 meaning that PulseView automatically fits all data to the views until either the
21 capture is finished or the Zoom-to-Fit button is clicked again.
22 If you want this feature but don't want to always have to click the button, you
23 can enable the "Always Zoom-to-Fit" option in the settings.
24
25 === Cursors and Markers
26
27 Just looking at the signal data however is usually not sufficient. A lot of times,
28 you'll want to make sure that timings are honored and the bit times are like what
29 you'd expect. To do so, you'll want to use cursors and markers.
30
31 In the picture above, you can enable the cursor by clicking on the cursor button.
32 You can move both of its boundaries around by clicking on the blue flags in the
33 time scale area. The area between the two boundary lines shows the time distance,
34 its inverse (i.e. the frequency) and/or the number of samples encompassed. If there's
35 not enough space to see these, you can either zoom in until it shows, hover the mouse
36 cursor over the label in the middle or right-click on the label to  configure what
37 you want to see. You can also move both boundaries at the same time by dragging said
38 label.
39
40 image::pv_cursors_markers.png[]
41
42 <1> Cursors button, showing enabled state
43 <2> Cursor
44 <3> Marker
45
46 Markers are movable indicators that you can create wherever you like on the
47 time scale - just double-click on it and it'll create one for you where your
48 mouse cursor is at the time, or use the context menu when right-clicking on
49 the ruler or a signal trace.
50 You can click on its label and you'll have the option to change its name, or
51 drag it to reposition it.
52
53 When you have multiple markers, you can have PulseView show you the time difference
54 between the markers by hovering over one of them, like so:
55
56 image::pv_marker_deltas.png[]
57
58 This works on the cursor, too.
59
60 Speaking of which - if you want to place or move the cursor ranges quickly, you
61 can also press '1' and '2' on your keyboard to attach either side to your mouse
62 cursor. They will stay put when you either press Esc or click with the left
63 mouse button. This also works when the cursor isn't even showing, so using this
64 method allows you to place the cursor quickly without having to enable it first.
65
66 [NOTE]
67 For timing comparison purposes, you can also enable a vertical marker line that
68 follows your mouse cursor: _Settings_ -> _Views_ -> _Highlight mouse cursor_
69
70 [NOTE]
71 There is also a special kind of marker that appears for each time the data
72 acquisition device has triggered. It cannot be moved and appears as a vertical
73 dashed blue line.
74
75 === Special-Purpose Decoders
76
77 There are some decoders available that analyze the data instead of decoding it.
78 You can make use of them to examine various properties of the signals that are
79 of interest to you.
80
81 Among them are:
82
83 * Counter - counts pulses and/or groups of pulses (i.e. words)
84 * Guess bitrate - guesses the bitrate when using a serial protocol
85 * Jitter - determines the jitter (variance) of a signal
86 * Timing - shows the time passing between the chosen signal edges
87
88 === Other Features
89
90 ==== Signal Label Area Resizing
91 Trace Views also allow you to maximize the viewing area by minimizing the area
92 occupied by the label area on the left. To do this, simply position the mouse
93 cursor at the right edge of the label area (or left edge of the viewing area).
94 Your mouse cursor will change shape and you now can drag the border.
95
96 This way, you can give signals long, expressive names without clogging up the
97 view area.
98
99 ==== Multiple Views
100 You can create multiple views by clicking on the "New View" button on the very
101 left of the toolbar. These can be rearranged as you wish.
102
103 ==== Session Saving/Restoring
104 When closing PulseView, it automatically saves the sessions you currently have
105 open, including the signal configuration and any protocol decoders you might
106 have added. The next time you start it again, it'll be restored to its
107 previous state.
108
109 This metadata is also saved with every .sr file you save so that the next time
110 you open the .sr file, your signal configurations, views and decoders are
111 restored. These metadata files have the ending .pvs (PulseView Setup) and can
112 be edited in any text editor if you wish to change something manually.
113
114 Additionally, you can save or load this metadata at any time using the
115 save/load buttons.