/
README
292 lines (202 loc) · 9.8 KB
/
README
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
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
NAME
Text::LookUpTable - Perl5 module for text based look up table operations
SYNOPSIS
$tbl = Text::LookUpTable->load_file('my_table.tbl');
$tbl = Text::LookUpTable->load($str_tbl);
$tbl = Text::LookUpTable->build($x_size, $y_size, $x_title, $y_title);
print $tbl;
$str_tbl = "$tbl";
$tbl->save_file();
$tbl->save_file('my_table.tbl');
$val = $tbl->get($x, $y);
$tbl->set($x, $y, $val);
@diff_coords = $tbl->diff($tbl2);
$diffp = $tbl->diff($tbl2, 1); # true/false no coordinates
@xdiffs = $tb1->diff_x_coords($tb2);
@ydiffs = $tb1->diff_y_coords($tb2);
@x_coords = $tbl->get_x_coords();
@y_coords = $tbl->get_y_coords();
$res = $tbl->set_x_coords(@x_coords);
$res = $tbl->set_y_coords(@y_coords);
$str_plot = $tbl->as_plot('R');
$str_plot = $tbl->as_plot('Maxima');
print FILE $str_plot;
$tbl_copy = $tbl->copy();
DESCRIPTION
Text::LookUpTable provides operations for creating, storing, displaying,
plotting, loading, and querying a *look up table* structure. The format
of the stored structure is designed to be visually easy to understand so
that it can be easily edited using a text editor.
The authors inteded use of this library is to allow a user to edit a
text file representation of a look up table which can then be loaded in
to an embedded controller such as MegaSquirt [http://www.msextra.com].
Additional code would be needed to convert this generic structure to
whatever application specific format is required.
What is a *look up table* and how is it different than a *table*? A
*look up table* is commonly used in embedded controllers to avoid the
use of costly floating pointing operations by looking up a value based
on the input coordiantes. A function with two inputs (f(x, y)) which
would use floating point operations can be represented (with some loss
in precsion) as a table.
In contrast a *table* (or spreadsheet) has any number of columns/rows.
The columns can be of different types. And a table does not try to
represent any sort of function, it just stores data.
STRING FORMAT
The format of the look up table when stored to a string or file should
look like the example below.
rpm
[1000] [1500] [2000] [2500]
[100] 14.0 15.5 16.4 17.9
map [90] 13.0 14.5 15.3 16.8
[80] 12.0 13.5 14.2 15.7
The x (across top) and y (left column) coordinates have their values
enclosed in square brackets. All values must be present. And the titles
can only span one line. There can be any number of lines and spaces as
long as the values can be discerned. When saving and restoring a table
the original spacing will not be preserved.
The x values start at offset 0 at the left and increase towards the
right. The y values start at offset 0 at the bottom and increase upward.
OPERATIONS
Text::LookUpTable->load($string);
Returns: a new table object on success, FALSE on error
Creates a new look up table object by parsing the given string. See the
section *STRING FORMAT* for details on format it expects.
If you want to load a table from a *file* see *load_file*.
Text::LookUpTable->load_file($file)
Returns: new object on success, FALSE on error
Works like *load* but obtains the text from the $file first.
Stores the name of file so that save_file can be used without having to
specify the file again.
Text::LookUpTable->build($x_size, $y_size, $x_title, $y_title)
Returns: new object on success, FALSE on error
Creates a blank object with all values initialized to zero and
dimensions of $x_size and $y_size.
Text::LookUpTable->copy($obj)
Returns: new object on success, FALSE on error
Creates a new object as a copy of the given object.
$tbl->as_string();
Returns string on success, FALSE on error.
Convert the object to a string representation.
This operation is used to overload the string operation so the shorthand
form can be used.
print $tbl; # print the object as a string
$to_save = "$tbl"; # get the string format to be saved
The long hand form $tbl->as_string(); should not normally be needed.
$tbl->save_file($file);
Returns TRUE on success, FALSE on error
Optional argument $file, can specify the file to save to. If ommitted it
will save to the last file that was used. If no last file is stored it
will produce an error.
$tbl->get_*_coords();
Returns list of all x/y coordinates on success, FALSE on error
Offset 0 for the X coordinates start at the LEFT of the displayed table
and increases RIGHTWARD.
Offset 0 for the Y coordinates start at the BOTTOM of the displayed
table and increases UPWARD.
@xs = $tbl->get_x_coords();
@ys = $tbl->get_y_coords();
$tbl->set_*_coords(@new_coords);
Returns TRUE on success, FALSE on error
Assigns the x/y coordinates to the values given in the list.
The coordinates must be in ascending order so that lookup_points, etc
will work correctly.
$res = $tbl->set_x_coords(@new_x_coords);
$res = $tbl->set_y_coords(@new_y_coords);
$tbl->set($x, $y, $val);
Returns TRUE on success OR FALSE on error
Set the value to $val at the given $x and $y coordinate offset.
$tbl->get($x, $y);
Returns $value on success, FALSE on error
Get the value at the given horizontal ($x) and vertical ($y) offset.
$tbl->lookup_points($val_x, $val_y, $range);
Returns @points (see below) on success, FALSE on error
Lookup the points for the given values.
The $range argument defines how far from the nearest point in the x and
y direction the resulting set of points should include.
Unlike offsets (see get()) which correspond to one point, a lookup based
on values may correspond to multiple points of varying degrees (closer
to some points than others).
Suppose, for example, we are given the following map
rpm
[1000] [1500] [2000] [2500] [3000]
[100] 14.0 15.5 16.4 17.9 21.9
map [90] 13.0 14.5 15.3 16.8 21.9
[80] 12.0 13.5 14.2 15.7 20.5
[70] 12.0 13.5 14.2 15.7 20.1
[60] 12.0 13.5 14.2 15.7 18.2
A lookup of the x value of 2010 and a y value of 85 (notice the values
do not correspond exactly) and a range of 1 would select the points
shown below (show with an X).
@points = $tbl->lookup_points(2010, 85, 1);
rpm
[1000] [1500] [2000] [2500] [3000]
[100] 14.0 15.5 16.4 17.9 21.9
map [90] 13.0 X X X 21.9
[80] 12.0 X X X 20.5
[70] 12.0 X X X 20.1
[60] 12.0 13.5 14.2 15.7 18.2
The set of points returned would be (in no particular order)
([1, 1], [1, 2], [1, 3], [2, 1], [2, 2], [2, 3], ...)
And this set of points could then be used to retrieve and/or assign the
range of values.
$tb1->diff($tb2, $break);
Returns TRUE if different, FALSE otherwise.
If $break is FALSE it returns a list of positions that are different.
Determines whether the VALUES two tables are different. Does not check
if the coordinates or the titles are different.
If $break is FALSE return a complete list of coordinates that are
different. If $break is TRUE it breaks out and returns as soon it is
found that they are different for a slight performance improvement.
$tb1->diff_*_coords($tb2)
Returns list of differences on success, FALSE on error
@xdiffs = $tb1->diff_x_coords($tb2);
@ydiffs = $tb1->diff_y_coords($tb2);
$tbl->as_plot('plot type', [type specific args ...] );
Returns: string on success, FALSE on error
Convert the table to a representation suitable for plotting. The string
may need to be output to a file depending on how the plotting program is
called.
See below for the various plot types.
R [www.r-project.org]
The string can be output to a file and then the file can be sourced to
produce a plot. It depends upon the rgl library
[http://cran.r-project.org/web/packages/rgl/index.html].
$tbl->as_plot('R');
shell$ ./a.out > file.R
shell$ R
> source('file.R')
(plot displayed)
Maxima [maxima.sourceforge.net]
Example usage using lutasplot.pl utility (in bin directory).
shell$ lutasplot.pl veTable1 Maxima > veTable1.maxima
shell$ maxima
(%i1) batch("veTable1.maxima");
(..., plot output, etc)
PREREQUISITES
Module Version
------ -------
Text::Aligner 0.03
File::Slurp 9999.13
The version numbers given have been tested and shown to work
but other versions may work as well.
VERSION
This document refers to Text::LookUpTable version 0.07.
REFERENCES
[1] MegaSquirt Engine Management System
http://www.msextra.com
[2] R Project
http://www.r-project.org
[3] rgl: 3D visualization device system (OpenGL)
http://cran.r-project.org/web/packages/rgl/index.html
[4] Gnuplot
http://www.gnuplot.info
[5] Maxima
http://maxima.sourceforge.net
AUTHOR
Jeremiah Mahler <jmmahler@gmail.com>
CPAN ID: JERI
https://plus.google.com/+JeremiahMahler/about
COPYRIGHT
Copyright (c) 2014, Jeremiah Mahler. All Rights Reserved. This module is
free software. It may be used, redistributed and/or modified under the
same terms as Perl itself.