diff options
Diffstat (limited to 'Master/texmf-dist/doc/context/sources/general/manuals/graphics/graphics.tex')
-rw-r--r-- | Master/texmf-dist/doc/context/sources/general/manuals/graphics/graphics.tex | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/graphics/graphics.tex b/Master/texmf-dist/doc/context/sources/general/manuals/graphics/graphics.tex new file mode 100644 index 00000000000..7c1000c4e15 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/graphics/graphics.tex @@ -0,0 +1,415 @@ +% language=uk + +\usemodule[article-basic] +\usemodule[abbreviations-smallcaps] +\usemodule[setups-basics] +\usemodule[scite] + +% \setupbodyfont +% [dejavu] + +\loadsetups[context-en] + +\definecolor + [mysetupscolora] + [a=1, + t=.25, + r=.5, + g=.5] + +\definecolor + [mysetupscolorb] + [a=1, + t=.25, + g=.25, + b=.25] + +\definetextbackground + [mysetups] + [before=\blank, + after=\blank, + topoffset=10pt, + leftoffset=10pt, + location=paragraph, + backgroundcolor=mysetupscolora, + backgroundcolor=mysetupscolorb, + frame=off] + +\startsetups xml:setups:start + \starttextbackground[mysetups] +\stopsetups + +\startsetups xml:setups:stop + \stoptextbackground +\stopsetups + +\starttext + +\startbuffer[image] + \startluacode + + local min, max, random = math.min, math.max, math.random + + -- kind of self-explaining: + + local xsize = 210 + local ysize = 297 + local colordepth = 1 + local usemask = true + local colorspace = "rgb" + + -- initialization: + + local bitmap = graphics.bitmaps.new(xsize,ysize,colorspace,colordepth,usemask) + + -- filling the bitmap: + + local data = bitmap.data + local mask = bitmap.mask + local minmask = 100 + local maxmask = 200 + + for i=1,ysize do + local d = data[i] + local m = mask[i] + for j=1,xsize do + d[j] = { i, max(i,j), j, min(i,j) } + m[j] = random(minmask,maxmask) + end + end + + -- flushing the lot: + + graphics.bitmaps.tocontext(bitmap) + + \stopluacode +\stopbuffer + +\definelayer + [page] + [width=\paperwidth, + height=\paperheight] + +\setlayer + [page] + {\scale + [width=\paperwidth] + {\ignorespaces + \getbuffer[image]% + \removeunwantedspaces}} + +\setlayer + [page] + [preset=rightbottom, + hoffset=10mm, + voffset=45mm] + {\scale + [width=.6\paperwidth] + {Graphics}} + +% \setlayer +% [page] +% [preset=righttop, +% hoffset=10mm, +% voffset=20mm] +% {\rotate{\scale +% [width=.3\paperheight] +% {\ConTeXt\ MkIV}}} + +\setlayer + [page] + [preset=rightbottom, + hoffset=10mm, + voffset=20mm] + {\scale + [width=.6\paperwidth] + {Hans Hagen}} + +\startpagemakeup + \flushlayer[page] + \vfill +\stoppagemakeup + +\startsubject[title=Introduction] + +This manual is about integrating graphics your document. Doing this is not really +that complex so this manual will be short. Because graphic inclusion is related +to the backend some options will discussed. It's typical one of these manuals +that can grow over time. + +\stopsubject + +\startsubject[title=Basic formats] + +In \TEX\ a graphic is not really known as graphic. The core task of the engine is +to turn input into typeset paragraphs. By the time that happens the input has +become a linked list of so called nodes: glyphs, kerns, glue, rules, boxes and a +couple of more items. But, when doing the job, \TEX\ is only interested in +dimensions. + +In traditional \TEX\ an image inclusion happens via the extension primitive +\type {\special}, so you can think of something: + +\starttyping +\vbox to 10cm {% + \hbox to 4cm {% + \special{image foo.png width 4cm height 10cm}% + \hss + }% +} +\stoptyping + +When typesetting \TEX\ sees a box and uses its dimensions. It doesn't care what +is inside. The special itself is just a so called whatsit that is not +interpreted. When the page is eventually shipped out, the \DVI|-|to|-|whatever +driver interprets the special's content and embeds the image. + +It will be clear that this will only work correctly when the image dimensions are +communicated. That can happen in real dimensions, but using scale factors is also +a variant. In the latter case one has to somehow determine the original dimensions +in order to calculate the scale factor. When you embed \EPS\ images, which is the +usual case in for instance \DVIPS, you can use \TEX\ macros to figure out the +(high res) boundingbox, but for bitmaps that often meant that some external +program had to do the analysis. + +It sounds complex but in practice this was all quite doable. I say \quote {was} +because nowadays most \TEX\ users use an engine like \PDFTEX\ that doesn't need +an external program for generating the final output format. As a consequence it +has built-in support for analyzing and including images. There are additional +primitives that analyze the image and additional ones that inject them. + +\starttyping +\pdfximage + {foo.png}% +\pdfrefximage + \pdflastximage + width 4cm + height 10cm +\relax +\stoptyping + +A difference with traditional \TEX\ is that one doesn't need to wrap them into a +box. This is easier on the user (not that it matters much as often a macro +package hides this) but complicates the engine because suddenly it has to check a +so called extension whatsit node (representing the image) for dimensions. + +Therefore in \LUATEX\ this model has been replaced by one where an image +internally is a special kind of rule, which in turn means that the code for +checking the whatsit could go away as rules are already taken into account. The +same is true for reuseable boxes (xforms in \PDF\ speak). + +\starttyping +\useimageresource + {foo.png}% +\saveimageresource + \lastsavedimageresourceindex + width 4cm + height 10cm +\relax +\stoptyping + +While \DVIPS\ supported \EPS\ images, \PDFTEX\ and \LUATEX\ natively support +\PNG, \JPG\ en \PDF\ inclusion. The easiest to support is \JPG\ because the PDF\ +format supports so called \JPG\ compression in its full form. The engine only has +to pass the image blob plus a bit of extra information. Analyzing the file for +resolution, dimensions and colorspace is relative easy: consult some tables that +have this info and store it. No special libraries are needed for this kind of +graphics. + +A bit more work is needed for \PDF\ images. A \PDF\ file is a collection of +(possibly compressed) objects. These objects can themselves refer to other +objects so basically we we have a tree of objects. This means that when we embed +a page from a \PDF\ file, we start with embedding the (content stream of the) +page object and then embed all the objects it refers to, which is a recursive +process because those objects themselves can refer to objects. In the process we +keep track of which objects are copied so that when we include another page we +don't copy duplicates. + +A dedicated library is used for opening the file, and looking for objects that +tell us the dimensions and fetching objects that we need to embed. In \PDFTEX\ +the poppler library is used, but in \LUATEX\ we have switched to pplib which is +specially made for this engine (by Pawel Jackowski) as a consequence of some +interchange that we had at the 2018 Bacho\TEX\ meeting. This change of library +gives us a greater independency and a much smaller code base. After all, we only +need access to \PDF\ files and its objects. + +One can naively think that \PNG\ inclusion is as easy as \JPG\ inclusion because +\PDF\ supports \PNG\ compression. Well, this is indeed true, but it only supports +so called \PNG\ filter based compression. The image blob in a \PNG\ file +describes pixels in rows and columns where each row has a filter byte telling how +that row is to be interpreted. Pixel information can be derived from preceding +pixels, pixels above it, or a combination. Also some averaging can come into +play. This way repetitive information can (for instance) become for instance a +sequence of zeros because no change in pixel values took place. And such a +sequence can be compressed very well which is why the whole blob is compressed +with zlib. + +In \PDF\ zlib compression can be applied to object streams so that bit is +covered. In addition a stream can be \PNG\ compressed, which means that it can +have filter bytes that need to be interpreted. But the \PNG\ can do more: the +image blob is actual split in chunks that need to be assembled. The image +information can be interlaced which means that the whole comes in 7~seperate +chunks thet get overlayed in increasing accuracy. Then there can be an image mask +part of the blob and that mask needs to be separated in \PDF\ (think of +transparency). Pixels can refer to a palette (grayscale or color) and pixels can +be codes in~1, 2, 4, 8 or 16~bits where color images can have 3~bytes. When +multiple pixels are packed into one byte they need to be expanded. + +This all means that embedding \PNG\ file can demand a conversion and when you +have to do that each run, it has a performance hit. Normally, in a print driven +workflow, one will have straightforward \PNG\ images: 1 byte or 3 bytes which no +mask and not interlaced. These can be transferred directly to the \PDF\ file. In +all other cases it probably makes sense to convert the images beforehand (to +simple \PNG\ or just \PDF). + +So, to summarize the above: a modern \TEX\ engine supports image inclusion +natively but for \PNG\ images you might need to convert them beforehand if +runtime matters and one has to run many times. + +\stopsubject + +\startsubject[title=Inclusion] + +The command to include an image is: + +\showsetup{externalfigure} + +and its related settings are: + +\showsetup{setupexternalfigure} + +So you can say: + +\starttyping[option=TEX] +\externalfigure[cow.pdf][width=4cm] +\stoptyping + +The suffix is optional, which means that this will also work: + +\starttyping[option=TEX] +\externalfigure[cow][width=4cm] +\stoptyping + +\stopsubject + +\startsubject[title=Defining] + +{\em todo} + +\showsetup{useexternalfigure} +\showsetup{defineexternalfigure} +\showsetup{registerexternalfigure} + +\stopsubject + +\startsubject[title=Analyzing] + +{\em todo} + +\showsetup{getfiguredimensions} + +\showsetup{figurefilename} +\showsetup{figurefilepath} +\showsetup{figurefiletype} +\showsetup{figurefullname} +\showsetup{figureheight} +\showsetup{figurenaturalheight} +\showsetup{figurenaturalwidth} +\showsetup{figuresymbol} +\showsetup{figurewidth} + +\showsetup{noffigurepages} + +\stopsubject + +\startsubject[title=Collections] + +{\em todo} + +\showsetup{externalfigurecollectionmaxheight} +\showsetup{externalfigurecollectionmaxwidth} +\showsetup{externalfigurecollectionminheight} +\showsetup{externalfigurecollectionminwidth} +\showsetup{externalfigurecollectionparameter} +\showsetup{startexternalfigurecollection} + +\stopsubject + +\startsubject[title=Conversion] + +{\em todo} + +\stopsubject + +\startsubject[title=Figure databases] + +{\em todo} + +\showsetup{usefigurebase} + +\stopsubject + +\startsubject[title=Overlays] + +{\em todo} + +\showsetup{overlayfigure} +\showsetup{pagefigure} + +\stopsubject + +\startsubject[title=Scaling] + +Images are normally scaled proportionally but if needed you can give an +explicit height and width. The \type {\scale} command shares this property +and can be used to scale in the same way as \type {\externalfigure}. I will +illustrate this with an example. + +You can define your own bitmaps, like I did with the cover of this manual: + +\typebuffer[image][option=LUA] + +The actually inclusion of this image happened with: + +\starttyping[option=TEX] +\scale + [width=\paperwidth] + {\getbuffer[image]} +\stoptyping + +\stopsubject + +% \startsubject[title=The backend] +% +% Traditionally \TEX\ sees an image as just a box with dimensions and in \LUATEX\ +% it is actually a special kind of rule that carries information about what to +% inject in the final (\PDF) file. In regular \LUATEX\ the core formats \type +% {pdf}, \type {png}, \type {jpg} and \type {jp2} are dealt with by the backend but +% in \CONTEXT\ we can use \LUA\ instead. We might default to that method at some +% point but for now you need to enable that explicitly: +% +% \starttyping[option=TEX] +% \enabledirectrive[graphics.pdf.uselua] +% \enabledirectrive[graphics.jpg.uselua] +% \enabledirectrive[graphics.jp2.uselua] +% \enabledirectrive[graphics.png.uselua] +% \stoptyping +% +% All four can be enabled with: +% +% \starttyping[option=TEX] +% \enabledirectrive[graphics.uselua] +% \stoptyping +% +% Performance|-|wise only \PNG\ inclusion can be less efficient, but only when you +% use interlaced images or large images with masks. It makes no real sense in a +% professional workflow to use the (larger) interlaced images, and masks are seldom +% used at high resolutions, so in practice one will not really notice loss of +% performance. +% +% The advantage of this method is that we can provide more options, intercept bad +% images that make the backend abort and lessen the dependency on libraries. +% +% \stopsubject + +\stoptext |