summaryrefslogtreecommitdiff
path: root/meme/README
blob: d34b7129bf988fa0ba42eb5768f218a3b550dbee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
Mesh measurement utility
========================

Build requisites
----------------

SDL 1.2, SDL_gfx, libsdl-pango-dev, libgsl


Usage
-----

meme [-d dump.bmp] [-l logfile] [-m marker.gp] [-o overlay.gp ...]
  headless-dump-options path-to-STL-file
meme -s slice.gp [-n] path-to-STL-file


Mouse
-----

- move mouse: places the cursor on the vertex closes to the mouse pointer
- turn scroll wheel:
  - C key not held: zooms in or out
  - C key held: increase/decrease contrast
- click left button:
  - not on measurement point: set/move measurement point
  - on measurement point: cancel measurement point
- click right button:
  - delete both measurement points


Keyboard
--------

- C: enter contrast enhancement mode, see below
- D: write a screen dump to either file specified with "-d dump.bmp" or to
     meme-NNNN.bmp, where NNNN is the first unique number for which no file
     exists yet.
- E: highlight equal height, see below
- G: toggle grid (edges) display
- M: toggle mesh display
- N: cancel measurements and start new one at location of second measurement
     point (or at cursor, if there was no second measurement)
- O: toggle overlay and marker; see below
- P: toggle profiles display, see below
- Q: quit
- R: reload all overlays
- 1, 2, 3: select the respective overlay (if present)
- *: center and zoom to extents
- +: zooom in
- -: zoom out


Log file
--------

When a log file is specified with the -l option, the position of
measurement markers and of measurements is appended to this file each
time a marker is set.


Profiles
--------

Profiles show the intersections of the mesh with XZ and YZ planes placed
at the cursor location. The XZ profile is shown at the bottom of the window
(screen X is mesh X, screen Y is mesh Z) and the YZ profile is shown at
the right side (screen -X is mesh Z, screen Y is mesh Y).

Profiles are toggled with the P key.


Contrast enhancement
--------------------

Contrast enhancement mode can be entered by pressing and holding the C
key. When pressing C, the Z to greyscale mapping is adjusted such that
the Z value at the cursor position becomes the middle of the greyscale
range.

Contrast can be increased or decreased with the scroll wheel. Areas
that exceed the contrast range are shown in yellow.

The normal mapping is restored when releasing the C key.

If a Shift key is pressed when releasing C, the scroll wheel function is
returned to zooming, but the enhanced greyscale mapping stays active. To
reset it, press and release C without holding Shift.


Highlight equal
---------------

While pressing the E key, a contour line at the Z position at the cursor
is drawn in purple. Areas that are coplanar with that Z position are
filled. This is similar to contrast enhancement and intended for quick
estimation of where the cursor is located with respect to plateaus.


Overlay
-------

A set of lines in gnuplot format can be drawn over the scan data. The
file containing the lines (in model coordinates) is specified with the
-o option. The O key toggles overlay display.

The -o option can be used multiple times. The overlay to display is
selected with the numeric keys, starting with 1.

To better visualize overlays, the mesh can be toggled by pressing M.


Marker
------

Makers are similar to overlays and are used to indicate measurements or
to mark features in the mesh. Markers are read from the file specified
with the -m option. O toggles displaying of markers.

A marker only consisting of text is defined with the line
x y text

A marker indicating a measurement between points A and B is defined with
ax ay bx by text

The latter form can be extended with an offset (using the same coordinate
system) that is added to the start position of the text:
ax ay bx by ox oy text


Slicing
-------

An intersection of the mesh with a plane can be calculated using the -s
option. The plane is described by the slice file containing points
in the following format:

x y z [zoff]
...
[zglobal]

If the zoff value is present, it is added to the z coordinate. This can
be used to manually adjust coordinates obtained from the mesh. If a
global z offset is present anywhere in the file, it is added to all
points.

The output is a set of unconnected line segments, in Gnuplot format.

Two algorithms are available for interpolating between measurement
points: by default, the plane is simply intersected with a the mesh
edges connecting two points. If the -n option is given, the real
position of the edge is calculated considering the shape of the
scanning needle. This is illustrated in needle.fig


Headless screen dumps
---------------------

Non-interactive screen dumps (e.g., to generate documentation) can be
taken with the -D option and its many sub-options:

  -D xres yres

    Draws the mesh on a canvas of the specified size and then dumps it,
    as if pressing "D". If markers or an overlay have been specified,
    they are displayed. No other items (cursor, profiles, etc.) are
    shown.

  -C cx cy

    Show the cursor at the specified position.

  -E z zoom

    Enhance contrast by "zoom" levels around the height "z". This is
    similar to contrast enhancement by pressing "C".

  -M mx my

    Move the middle of the canvas to the specified position (in model
    coordinates).

  -P

    Show profiles. This is like toggling them on with "P".

  -Z zoom

    Set the zoom level. If "zoom" begins with a plus or minus sign, the
    default zoom level is changed accordingly. I.e., "+1" auto-zooms to
    show the whole mesh, then zooms in by one step.

  To prevent negative numbers on the command line from being
  mis-interpreted as options, they can be prefixed with a space, e.g.,
  " -10"


Workflow
--------

- load the STL file, ideally at a resolution of 100 um or better
- zoom into the area of interest

To measure vertical distances:

- use contrast enhancement mode to identity flat areas at the desired
  heights and place the measurement markers there. When both markers
  are present, a window with the measured distances will appear.

To measure horizontal distances:

- note that the meshes are not corrected for the size of the scanning
  needle, which has a hemispherical tip with a diameter of 0.8 mm and
  a conical shaft.

- use profiles and/or contrast enhancement to find the desired edges.
  Edges are typically located between the last point of a plateau and
  the adjacent point that is slightly below the plateau.

- left-click to place a measurement marker

- find the corresponding second point and place the second measurement
  marker

To clear a marker, move the cursor exactly on the marker and
left-click. To clear both markers, right-click.


Known bugs and limitations
--------------------------

- only suitable for 2.5 D scans, i.e., there it at most one vertex at
  any (x, y) position
- doesn't support other views than from the top
- doesn't support rotation
- profiles may overwrite each other (clear artefacts caused by this by
  zooming out and in again)
- contours aren't always closed lines - why ?