summaryrefslogtreecommitdiff
path: root/systems/doc/luatex/luatex-graphics.tex
blob: 3f12762b68b8499be3c863c98571f11d8d7a5d74 (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
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
% language=uk

% mp solve_path

\environment luatex-style

\startcomponent luatex-graphics

\startchapter[reference=graphics,title={The graphic libraries}]

\startsection[title={The \type {img} library}][library=img]

\topicindex {images}
\topicindex {images+library}
\topicindex {graphics}

The \type {img} library can be used as an alternative to \orm {pdfximage} and
\orm {pdfrefximage}, and the associated \quote {satellite} commands like \type
{\pdfximagebbox}. Image objects can also be used within virtual fonts via the
\type {image} command listed in~\in {section} [virtualfonts].

\subsection{\type {new}}

\libindex{new}

\startfunctioncall
<image> var = img.new()
<image> var = img.new(<table> image_spec)
\stopfunctioncall

This function creates a userdata object of type \quote {image}. The \type
{image_spec} argument is optional. If it is given, it must be a table, and that
table must contain a \type {filename} key. A number of other keys can also be
useful, these are explained below.

You can either say

\starttyping
a = img.new()
\stoptyping

followed by

\starttyping
a.filename = "foo.png"
\stoptyping

or you can put the file name (and some or all of the other keys) into a table
directly, like so:

\starttyping
a = img.new({filename='foo.pdf', page=1})
\stoptyping

The generated \type {<image>} userdata object allows access to a set of
user|-|specified values as well as a set of values that are normally filled in
and updated automatically by \LUATEX\ itself. Some of those are derived from the
actual image file, others are updated to reflect the \PDF\ output status of the
object.

There is one required user-specified field: the file name (\type {filename}). It
can optionally be augmented by the requested image dimensions (\type {width},
\type {depth}, \type {height}), user|-|specified image attributes (\type {attr}),
the requested \PDF\ page identifier (\type {page}), the requested boundingbox
(\type {pagebox}) for \PDF\ inclusion, the requested color space object (\type
{colorspace}).

The function \type {img.new} does not access the actual image file, it just
creates the \type {<image>} userdata object and initializes some memory
structures. The \type {<image>} object and its internal structures are
automatically garbage collected.

Once the image is scanned, all the values in the \type {<image>} except \type
{width}, \type {height} and \type {depth}, become frozen, and you cannot change
them any more.

You can use \type {pdf.setignoreunknownimages(1)} (or at the \TEX\ end the \lpr
{pdfvariable} \type {ignoreunknownimages}) to get around a quit when no known
image type is found (based on name or preamble). Beware: this will not catch
invalid images and we cannot guarantee side effects. A zero dimension image is
still included when requested. No special flags are set. A proper workflow will
not rely in such a catch but make sure that images are valid.

\subsection{\type {fields}}

\libindex{fields}

\startfunctioncall
<table> keys = img.fields()
\stopfunctioncall

This function returns a list of all the possible \type {image_spec} keys, both
user-supplied and automatic ones.

\starttabulate[|l|l|p|]
\DB field name             \BC type     \BC description \NC \NR
\TB
\NC \type{attr}            \NC string   \NC the image attributes for \LUATEX \NC \NR
\NC \type{bbox}            \NC table    \NC table with 4 boundingbox dimensions \type
                                            {llx}, \type {lly}, \type {urx} and \type
                                            {ury} overruling the \type {pagebox} entry \NC \NR
\NC \type{colordepth}      \NC number   \NC the number of bits used by the color space \NC \NR
\NC \type{colorspace}      \NC number   \NC the color space object number \NC \NR
\NC \type{depth}           \NC number   \NC the image depth for \LUATEX \NC \NR
\NC \type{filename}        \NC string   \NC the image file name \NC \NR
\NC \type{filepath}        \NC string   \NC the full (expanded) file name of the image\NC \NR
\NC \type{height}          \NC number   \NC the image height for \LUATEX \NC \NR
\NC \type{imagetype}       \NC string   \NC one of \type {pdf}, \type {png}, \type {jpg},
                                            \type {jp2} or \type {jbig2} \NC \NR
\NC \type{index}           \NC number   \NC the \PDF\ image name suffix \NC \NR
\NC \type{objnum}          \NC number   \NC the \PDF\ image object number \NC \NR
\NC \type{page}            \NC number   \NC the identifier for the requested image page \NC \NR
\NC \type{pagebox}         \NC string   \NC the requested bounding box, one of
                                            \type {none}, \type {media}, \type {crop},
                                            \type {bleed}, \type {trim}, \type {art} \NC \NR
\NC \type{pages}           \NC number   \NC the total number of available pages \NC \NR
\NC \type{rotation}        \NC number   \NC the image rotation from included \PDF\ file,
                                            in multiples of 90~deg. \NC \NR
\NC \type{stream}          \NC string   \NC the raw stream data for an \type {/Xobject}
                                            \type {/Form} object\NC \NR
\NC \type{transform}       \NC number   \NC the image transform, integer number 0..7 \NC \NR
\NC \type{orientation}     \NC number   \NC the (jpeg) image orientation, integer number 1..8
                                            (0 for unset) \NC \NR
\NC \type{width}           \NC number   \NC the image width for \LUATEX \NC \NR
\NC \type{xres}            \NC number   \NC the horizontal natural image resolution
                                            (in \DPI) \NC \NR
\NC \type{xsize}           \NC number   \NC the natural image width \NC \NR
\NC \type{yres}            \NC number   \NC the vertical natural image resolution
                                            (in \DPI) \NC \NR
\NC \type{ysize}           \NC number   \NC the natural image height \NC \NR
\NC \type{visiblefilename} \NC string   \NC when set, this name will find its way in the
                                            \PDF\ file as \type {PTEX} specification; when
                                            an empty string is assigned nothing is written
                                            to file; otherwise the natural filename is
                                            taken \NC \NR
\NC \type{userpassword}   \NC string   \NC  the userpassword needed for opening a \PDF\ file \NC \NR
\NC \type{ownerpassword}  \NC string   \NC  the ownerpassword needed for opening a \PDF\ file \NC \NR
\NC \type{keepopen}       \NC boolean  \NC  keep the \PDF\ file open \NC \NR
\NC \type{nobbox}         \NC boolean  \NC  don't add a boundingbox specification for streams \NC \NR
\NC \type{nolength}       \NC boolean  \NC  don't add length key nor compress for streams \NC \NR
\NC \type{nosize}         \NC boolean  \NC  don't add size fields for streams \NC \NR
\LL
\stoptabulate

A running (undefined) dimension in \type {width}, \type {height}, or \type
{depth} is represented as \type {nil} in \LUA, so if you want to load an image at
its \quote {natural} size, you do not have to specify any of those three fields.

The \type {stream} parameter allows to fabricate an \type {/XObject} \type
{/Form} object from a string giving the stream contents, e.g., for a filled
rectangle:

\startfunctioncall
a.stream = "0 0 20 10 re f"
\stopfunctioncall

When writing the image, an \type {/Xobject} \type {/Form} object is created, like
with embedded \PDF\ file writing. The object is written out only once. The \type
{stream} key requires that also the \type {bbox} table is given. The \type
{stream} key conflicts with the \type {filename} key. The \type {transform} key
works as usual also with \type {stream}.

The \type {bbox} key needs a table with four boundingbox values, e.g.:

\startfunctioncall
a.bbox = { "30bp", 0, "225bp", "200bp" }
\stopfunctioncall

This replaces and overrules any given \type {pagebox} value; with given \type
{bbox} the box dimensions coming with an embedded \PDF\ file are ignored. The
\type {xsize} and \type {ysize} dimensions are set accordingly, when the image is
scaled. The \type {bbox} parameter is ignored for non-\PDF\ images.

The \type {transform} allows to mirror and rotate the image in steps of 90~deg.
The default value~$0$ gives an unmirrored, unrotated image. Values $1-3$ give
counterclockwise rotation by $90$, $180$, or $270$~degrees, whereas with values
$4-7$ the image is first mirrored and then rotated counterclockwise by $90$,
$180$, or $270$~degrees. The \type {transform} operation gives the same visual
result as if you would externally preprocess the image by a graphics tool and
then use it by \LUATEX. If a \PDF\ file to be embedded already contains a \type
{/Rotate} specification, the rotation result is the combination of the \type
{/Rotate} rotation followed by the \type {transform} operation.

\subsection{\type {scan}}

\libindex{scan}

\startfunctioncall
<image> var = img.scan(<image> var)
<image> var = img.scan(<table> image_spec)
\stopfunctioncall

When you say \type {img.scan(a)} for a new image, the file is scanned, and
variables such as \type {xsize}, \type {ysize}, image \type {type}, number of
\type {pages}, and the resolution are extracted. Each of the \type {width}, \type
{height}, \type {depth} fields are set up according to the image dimensions, if
they were not given an explicit value already. An image file will never be
scanned more than once for a given image variable. With all subsequent \type
{img.scan(a)} calls only the dimensions are again set up (if they have been
changed by the user in the meantime).

For ease of use, you can do right-away a

\starttyping
<image> a = img.scan { filename = "foo.png" }
\stoptyping

without a prior \type {img.new}.

Nothing is written yet at this point, so you can do \type {a=img.scan}, retrieve
the available info like image width and height, and then throw away \type {a}
again by saying \type {a=nil}. In that case no image object will be reserved in
the PDF, and the used memory will be cleaned up automatically.

\subsection{\type {copy}}

\libindex{copy}

\startfunctioncall
<image> var = img.copy(<image> var)
<image> var = img.copy(<table> image_spec)
\stopfunctioncall

If you say \type {a = b}, then both variables point to the same \type {<image>}
object. if you want to write out an image with different sizes, you can do
\type {b = img.copy(a)}.

Afterwards, \type {a} and \type {b} still reference the same actual image
dictionary, but the dimensions for \type {b} can now be changed from their
initial values that were just copies from \type {a}.

\subsection{\type {write}, \type {immediatewrite}, \type {immediatewriteobject}}

\topicindex {images+injection}
\topicindex {images+immediate}
\topicindex {images+object}

\libindex{write}
\libindex{immediatewrite}
\libindex{immediatewriteobject}

\startfunctioncall
<image> var = img.write(<image> var)
<image> var = img.write(<table> image_spec)
\stopfunctioncall

By \type {img.write(a)} a \PDF\ object number is allocated, and a rule node of
subtype \type {image} is generated and put into the output list. By this the
image \type {a} is placed into the page stream, and the image file is written out
into an image stream object after the shipping of the current page is finished.

Again you can do a terse call like

\starttyping
img.write { filename = "foo.png" }
\stoptyping

The \type {<image>} variable is returned in case you want it for later
processing. You can also write an object.

By \type {img.immediatewrite(a)} a \PDF\ object number is allocated, and the
image file for image \type {a} is written out immediately into the \PDF\ file as
an image stream object (like with \prm {immediate}\orm {pdfximage}). The object
number of the image stream dictionary is then available by the \type {objnum}
key. No \type {pdf_refximage} whatsit node is generated. You will need an
\type {img.write(a)} or \type {img.node(a)} call to let the image appear on the
page, or reference it by another trick; else you will have a dangling image
object in the \PDF\ file.

\startfunctioncall
<image> var = img.immediatewrite(<image> var)
<image> var = img.immediatewrite(<table> image_spec)
\stopfunctioncall

Also here you can do a terse call like

\starttyping
a = img.immediatewrite { filename = "foo.png" }
\stoptyping

The \type {<image>} variable is returned and you will most likely need it.

The next function is kind of special as it copies an object from a (\PDF) image
file. This features is experimental and might disappear.

\startfunctioncall
<integer> objnum = img.immediatewriteobject(<image> var, <integer> objnum)
<integer> objnum = img.immediatewriteobject(<table> image_spec, <integer> objnum)
\stopfunctioncall

\subsection{\type {node}}

\libindex{node}

\startfunctioncall
<node> n = img.node(<image> var)
<node> n = img.node(<table> image_spec)
\stopfunctioncall

This function allocates a \PDF\ object number and returns a whatsit node of
subtype \type {pdf_refximage}, filled with the image parameters \type {width},
\type {height}, \type {depth}, and \type {objnum}. Also here you can do a terse
call like:

\starttyping
n = img.node ({ filename = "foo.png" })
\stoptyping

This example outputs an image:

\starttyping
node.write(img.node{filename="foo.png"})
\stoptyping

\subsection{\type {types}}

\topicindex {images+types}

\libindex{types}

\startfunctioncall
<table> types = img.types()
\stopfunctioncall

This function returns a list with the supported image file type names, currently
these are \type {pdf}, \type {png}, \type {jpg}, \type {jp2} (JPEG~2000), and
\type {jbig2}.

\subsection{\type {boxes}}

\libindex{boxes}

\startfunctioncall
<table> boxes = img.boxes()
\stopfunctioncall

This function returns a list with the supported \PDF\ page box names, currently
these are \type {media}, \type {crop}, \type {bleed}, \type {trim}, and \type
{art}, all in lowercase.

The \PDF\ file is kept open after its properties are determined. After inclusion,
which happens when the page that references the image is flushed, the file is
closed. This means that when you have thousands of images on one page, your
operating system might decide to abort the run. When you include more than one
page from a \PDF\ file you can set the \type {keepopen} flag when you allocate an
image object, or pass the \type {keepopen} directive when you refer to the image
with \lpr {useimageresource}. This only makes sense when you embed many pages.
An \prm {immediate} applied to \lpr {saveimageresource} will also force a
close after inclusion.

\starttyping
\immediate\useimageresource{foo.pdf}%
          \saveimageresource         \lastsavedimageresourceindex % closed
          \useimageresource{foo.pdf}%
          \saveimageresource         \lastsavedimageresourceindex % kept open
          \useimageresource{foo.pdf}%
          \saveimageresource keepopen\lastsavedimageresourceindex % kept open

\directlua{img.write(img.scan{ file = "foo.pdf" })}                  % closed
\directlua{img.write(img.scan{ file = "foo.pdf", keepopen = true })} % kept open
\stoptyping

\stopsection

\startsection[title={The \type {mplib} library}][library=mplib]

\topicindex {\METAPOST}
\topicindex {\METAPOST+mplib}
\topicindex {images+mplib}
\topicindex {images+\METAPOST}

\libindex{version}

The \MP\ library interface registers itself in the table \type {mplib}. It is
based on \MPLIB\ version \ctxlua {context(mplib.version())}.

\subsection{\type {new}}

\libindex{new}

To create a new \METAPOST\ instance, call

\startfunctioncall
<mpinstance> mp = mplib.new({...})
\stopfunctioncall

This creates the \type {mp} instance object. The argument hash can have a number
of different fields, as follows:

\starttabulate[|l|l|pl|pl|]
\DB name               \BC type     \BC description              \BC default           \NC \NR
\TB
\NC \type{error_line}  \NC number   \NC error line width         \NC 79                \NC \NR
\NC \type{print_line}  \NC number   \NC line length in ps output \NC 100               \NC \NR
\NC \type{random_seed} \NC number   \NC the initial random seed  \NC variable          \NC \NR
\NC \type{math_mode}   \NC string   \NC the number system to use:
                                        \type {scaled},
                                        \type {double} or
                                      % \type {binary} or
                                        \type {decimal}          \NC \type {scaled}    \NC \NR
\NC \type{interaction} \NC string   \NC the interaction mode:
                                        \type {batch},
                                        \type {nonstop},
                                        \type {scroll} or
                                        \type {errorstop}        \NC \type {errorstop} \NC \NR
\NC \type{job_name}    \NC string   \NC \type {--jobname}        \NC \type {mpout}     \NC \NR
\NC \type{find_file}   \NC function \NC a function to find files \NC only local files  \NC \NR
\LL
\stoptabulate

The binary mode is no longer available in the \LUATEX\ version of \MPLIB. It
offers no real advantage and brings a ton of extra libraries with platform
specific properties that we can now avoid. We might introduce a high resolution
scaled variant at some point but only when it pays of performance wise.

The \type {find_file} function should be of this form:

\starttyping
<string> found = finder (<string> name, <string> mode, <string> type)
\stoptyping

with:

\starttabulate[|l|p|]
\DB name        \BC the requested file \NC \NR
\TB
\NC \type{mode} \NC the file mode: \type {r} or \type {w} \NC \NR
\NC \type{type} \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map},
                    \type {pfb}, \type {enc} \NC \NR
\LL
\stoptabulate

Return either the full path name of the found file, or \type {nil} if the file
cannot be found.

Note that the new version of \MPLIB\ no longer uses binary mem files, so the way
to preload a set of macros is simply to start off with an \type {input} command
in the first \type {execute} call.

When you are processing a snippet of text starting with \type {btex} and
ending with either \type {etex} or \type {verbatimtex}, the \METAPOST\
\type {texscriptmode} parameter controls how spaces and newlines get honoured.
The default value is~1. Possible values are:

\starttabulate[|l|p|]
\DB name      \BC meaning \NC \NR
\TB
\NC \type {0} \NC no newlines \NC \NR
\NC \type {1} \NC newlines in \type {verbatimtex} \NC \NR
\NC \type {2} \NC newlines in \type {verbatimtex} and \type {etex} \NC \NR
\NC \type {3} \NC no leading and trailing strip in \type {verbatimtex} \NC \NR
\NC \type {4} \NC no leading and trailing strip in \type {verbatimtex} and \type {btex} \NC \NR
\LL
\stoptabulate

That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes.
An \type {etex} has to be followed by a space or \type {;} or be at the end of a
line and preceded by a space or at the beginning of a line.

\subsection{\type {statistics}}

\libindex{statistics}

You can request statistics with:

\startfunctioncall
<table> stats = mp:statistics()
\stopfunctioncall

This function returns the vital statistics for an \MPLIB\ instance. There are
four fields, giving the maximum number of used items in each of four allocated
object classes:

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{main_memory} \NC number \NC memory size \NC \NR
\NC \type{hash_size}   \NC number \NC hash size\NC \NR
\NC \type{param_size}  \NC number \NC simultaneous macro parameters\NC \NR
\NC \type{max_in_open} \NC number \NC input file nesting levels\NC \NR
\LL
\stoptabulate

Note that in the new version of \MPLIB, this is informational only. The objects
are all allocated dynamically, so there is no chance of running out of space
unless the available system memory is exhausted.

\subsection{\type {execute}}

\libindex{execute}

You can ask the \METAPOST\ interpreter to run a chunk of code by calling

\startfunctioncall
<table> rettable = execute(mp,"metapost code")
\stopfunctioncall

for various bits of \METAPOST\ language input. Be sure to check the \type
{rettable.status} (see below) because when a fatal \METAPOST\ error occurs the
\MPLIB\ instance will become unusable thereafter.

Generally speaking, it is best to keep your chunks small, but beware that all
chunks have to obey proper syntax, like each of them is a small file. For
instance, you cannot split a single statement over multiple chunks.

In contrast with the normal stand alone \type {mpost} command, there is
\notabene {no} implied \quote{input} at the start of the first chunk.

\subsection{\type {finish}}

\libindex{finish}

\startfunctioncall
<table> rettable = finish(mp)
\stopfunctioncall

If for some reason you want to stop using an \MPLIB\ instance while processing is
not yet actually done, you can call \type finish}. Eventually, used memory
will be freed and open files will be closed by the \LUA\ garbage collector, but
an explicit \type finish} is the only way to capture the final part of the
output streams.

\subsection{Result table}

\libindex {fields}

The return value of \type {execute} and \type {finish} is a table with a
few possible keys (only \type {status} is always guaranteed to be present).

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{log}    \NC string \NC output to the \quote {log} stream \NC \NR
\NC \type{term}   \NC string \NC output to the \quote {term} stream \NC \NR
\NC \type{error}  \NC string \NC output to the \quote {error} stream
                                 (only used for \quote {out of memory}) \NC \NR
\NC \type{status} \NC number \NC the return value:
                                 \type {0} = good,
                                 \type {1} = warning,
                                 \type {2} = errors,
                                 \type {3} = fatal error \NC \NR
\NC \type{fig}    \NC table  \NC an array of generated figures (if any) \NC \NR
\LL
\stoptabulate

When \type {status} equals~3, you should stop using this \MPLIB\ instance
immediately, it is no longer capable of processing input.

If it is present, each of the entries in the \type {fig} array is a userdata
representing a figure object, and each of those has a number of object methods
you can call:

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{boundingbox}  \NC function \NC returns the bounding box, as an array of 4
                                         values \NC \NR
\NC \type{postscript}   \NC function \NC returns a string that is the ps output of the
                                         \type {fig}. this function accepts two optional
                                         integer arguments for specifying the values of
                                         \type {prologues} (first argument) and \type
                                         {procset} (second argument) \NC \NR
\NC \type{svg}          \NC function \NC returns a string that is the svg output of the
                                         \type {fig}. This function accepts an optional
                                         integer argument for specifying the value of
                                         \type {prologues} \NC \NR
\NC \type{objects}      \NC function \NC returns the actual array of graphic objects in
                                         this \type {fig} \NC \NR
\NC \type{copy_objects} \NC function \NC returns a deep copy of the array of graphic
                                         objects in this \type {fig} \NC \NR
\NC \type{filename}     \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\
                                         output would have written to in stand alone
                                         mode \NC \NR
\NC \type{width}        \NC function \NC the \type {fontcharwd} value \NC \NR
\NC \type{height}       \NC function \NC the \type {fontcharht} value \NC \NR
\NC \type{depth}        \NC function \NC the \type {fontchardp} value \NC \NR
\NC \type{italcorr}     \NC function \NC the \type {fontcharit} value \NC \NR
\NC \type{charcode}     \NC function \NC the (rounded) \type {charcode} value \NC \NR
\LL
\stoptabulate

Note: you can call \type {fig:objects()} only once for any one \type {fig}
object!

When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the
first set of coordinates is larger than the second set, the picture is empty.

Graphical objects come in various types that each has a different list of
accessible values. The types are: \type {fill}, \type {outline}, \type {text},
\type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type {stop_bounds},
\type {special}.

There is a helper function (\type {mplib.fields(obj)}) to get the list of
accessible values for a particular object, but you can just as easily use the
tables given below.

All graphical objects have a field \type {type} that gives the object type as a
string value; it is not explicit mentioned in the following tables. In the
following, \type {number}s are \POSTSCRIPT\ points represented as a floating
point number, unless stated otherwise. Field values that are of type \type
{table} are explained in the next section.

\subsubsection{fill}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{path}       \NC table  \NC the list of knots \NC \NR
\NC \type{htap}       \NC table  \NC the list of knots for the reversed trajectory \NC \NR
\NC \type{pen}        \NC table  \NC knots of the pen \NC \NR
\NC \type{color}      \NC table  \NC the object's color \NC \NR
\NC \type{linejoin}   \NC number \NC line join style (bare number)\NC \NR
\NC \type{miterlimit} \NC number \NC miterlimit\NC \NR
\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
\NC \type{postscript} \NC string \NC the postscript text \NC \NR
\LL
\stoptabulate

The entries \type {htap} and \type {pen} are optional.

\subsubsection{outline}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{path}       \NC table  \NC the list of knots \NC \NR
\NC \type{pen}        \NC table  \NC knots of the pen \NC \NR
\NC \type{color}      \NC table  \NC the object's color \NC \NR
\NC \type{linejoin}   \NC number \NC line join style (bare number) \NC \NR
\NC \type{miterlimit} \NC number \NC miterlimit \NC \NR
\NC \type{linecap}    \NC number \NC line cap style (bare number) \NC \NR
\NC \type{dash}       \NC table  \NC representation of a dash list \NC \NR
\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
\NC \type{postscript} \NC string \NC the postscript text \NC \NR
\LL
\stoptabulate

The entry \type {dash} is optional.

\subsubsection{text}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{text}       \NC string \NC the text \NC \NR
\NC \type{font}       \NC string \NC font tfm name \NC \NR
\NC \type{dsize}      \NC number \NC font size \NC \NR
\NC \type{color}      \NC table  \NC the object's color \NC \NR
\NC \type{width}      \NC number \NC \NC \NR
\NC \type{height}     \NC number \NC \NC \NR
\NC \type{depth}      \NC number \NC \NC \NR
\NC \type{transform}  \NC table  \NC a text transformation \NC \NR
\NC \type{prescript}  \NC string \NC the prescript text \NC \NR
\NC \type{postscript} \NC string \NC the postscript text \NC \NR
\LL
\stoptabulate

\subsubsection{special}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{prescript} \NC string \NC special text \NC \NR
\LL
\stoptabulate

\subsubsection{start_bounds, start_clip}

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{path} \NC table \NC the list of knots \NC \NR
\LL
\stoptabulate

\subsubsection{stop_bounds, stop_clip}

Here are no fields available.

\subsection{Subsidiary table formats}

\subsubsection{Paths and pens}

Paths and pens (that are really just a special type of paths as far as \MPLIB\ is
concerned) are represented by an array where each entry is a table that
represents a knot.

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{left_type}  \NC string \NC when present: endpoint, but usually absent \NC \NR
\NC \type{right_type} \NC string \NC like \type {left_type} \NC \NR
\NC \type{x_coord}    \NC number \NC X coordinate of this knot \NC \NR
\NC \type{y_coord}    \NC number \NC Y coordinate of this knot \NC \NR
\NC \type{left_x}     \NC number \NC X coordinate of the precontrol point of this knot \NC \NR
\NC \type{left_y}     \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR
\NC \type{right_x}    \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR
\NC \type{right_y}    \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR
\LL
\stoptabulate

There is one special case: pens that are (possibly transformed) ellipses have an
extra string-valued key \type {type} with value \type {elliptical} besides the
array part containing the knot list.

\subsubsection{Colors}

A color is an integer array with 0, 1, 3 or 4 values:

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{0} \NC marking only \NC no values                                                     \NC \NR
\NC \type{1} \NC greyscale    \NC one value in the range $(0,1)$, \quote {black} is $0$         \NC \NR
\NC \type{3} \NC \RGB         \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$  \NC \NR
\NC \type{4} \NC \CMYK        \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR
\LL
\stoptabulate

If the color model of the internal object was \type {uninitialized}, then it was
initialized to the values representing \quote {black} in the colorspace \type
{defaultcolormodel} that was in effect at the time of the \type {shipout}.

\subsubsection{Transforms}

Each transform is a six|-|item array.

\starttabulate[|l|l|p|]
\DB index  \BC type \BC explanation \NC \NR
\TB
\NC \type{1} \NC number \NC represents x  \NC \NR
\NC \type{2} \NC number \NC represents y  \NC \NR
\NC \type{3} \NC number \NC represents xx \NC \NR
\NC \type{4} \NC number \NC represents yx \NC \NR
\NC \type{5} \NC number \NC represents xy \NC \NR
\NC \type{6} \NC number \NC represents yy \NC \NR
\LL
\stoptabulate

Note that the translation (index 1 and 2) comes first. This differs from the
ordering in \POSTSCRIPT, where the translation comes last.

\subsubsection{Dashes}

Each \type {dash} is two-item hash, using the same model as \POSTSCRIPT\ for the
representation of the dashlist. \type {dashes} is an array of \quote {on} and
\quote {off}, values, and \type {offset} is the phase of the pattern.

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{dashes} \NC hash   \NC an array of on-off numbers \NC \NR
\NC \type{offset} \NC number \NC the starting offset value  \NC \NR
\LL
\stoptabulate

\subsection{Pens and \type {pen_info}}

\libindex{pen_info}

There is helper function (\type {pen_info(obj)}) that returns a table containing
a bunch of vital characteristics of the used pen (all values are floats):

\starttabulate[|l|l|p|]
\DB field  \BC type \BC explanation \NC \NR
\TB
\NC \type{width} \NC number \NC width of the pen \NC \NR
\NC \type{sx}    \NC number \NC $x$ scale        \NC \NR
\NC \type{rx}    \NC number \NC $xy$ multiplier  \NC \NR
\NC \type{ry}    \NC number \NC $yx$ multiplier  \NC \NR
\NC \type{sy}    \NC number \NC $y$ scale        \NC \NR
\NC \type{tx}    \NC number \NC $x$ offset       \NC \NR
\NC \type{ty}    \NC number \NC $y$ offset       \NC \NR
\LL
\stoptabulate

\subsection{Character size information}

These functions find the size of a glyph in a defined font. The \type {fontname}
is the same name as the argument to \type {infont}; the \type {char} is a glyph
id in the range 0 to 255; the returned \type {w} is in AFM units.

\subsubsection{\type {char_width}}

\libindex{char_width}

\startfunctioncall
<number> w = char_width(mp,<string> fontname, <number> char)
\stopfunctioncall

\subsubsection{\type {char_height}}

\libindex{char_height}

\startfunctioncall
<number> w = char_height(mp,<string> fontname, <number> char)
\stopfunctioncall

\subsubsection{\type {char_depth}}

\libindex{char_depth}

\startfunctioncall
<number> w = char_depth(mp,<string> fontname, <number> char)
\stopfunctioncall

\subsubsection{\type {get_[boolean|numeric|string|path]}}

\libindex{get_boolean}
\libindex{get_numeric}
\libindex{get_path}
\libindex{get_string}

When a script call brings you from the \METAPOST\ run (temporarily) back to
\LUA\ you can access variables, but only if they are known (so for instance
anonymous capsules like loop variables are not accessible).

\startfunctioncall
<boolean> w = get_boolean(mp,<string> name)
<number>  n = get_numeric(mp,<string> name)
<string>  s = get_string (mp,<string> name)
<table>   p = get_path   (mp,<string> name)
\stopfunctioncall

The path is returned a a table with subtables that have six numbers: the
coordinates of the point, pre- and postcontrol. A \type {cycle} fields indicates
if a path is cyclic.

\stopsection

\stopchapter