% language=us runpath=texruns:manuals/workflows

\environment workflows-style

\startcomponent workflows-graphics

\startchapter[title=Graphics]

\startsection[title=Bad names]

After many years of using \CONTEXT\ in workflows where large amounts of source
files as well as graphics were involved we can safely say that it's hard for
publishers to control the way these are named. This is probably due to the fact
that in a click|-|and|-|point based desktop publishing workflow names don't
matter as one stays on one machine, and names are only entered once (after that
these names become abstractions and get cut and pasted). Proper consistent
resource managament is simply not part of the flow.

This means that you get names like:

\starttyping
foo_Bar_01_03-a.EPS
foo__Bar-01a_03.eps
foo__Bar-01a_03.eps
foo BarA  01-03.eps
\stoptyping

Especially when a non proportional screen font is used multiple spaces can look
like one. In fancy screen fonts upper and lowercase usage might get obscured. It
really makes one wonder if copy|-|editing or adding labels to graphics isn't
suffering from the same problem.

Anyhow, as in an automated rendering workflow the rendering is often the last
step you can imagine that when names get messed up it's that last step that gets
blamed. It's not that hard to sanitize names of files on disk as well as in the
files that refer to them, and we normally do that we have complete control. This
is no option when all the resources are synchronzied from elsewhere. In that case
the only way out is signaling potential issues. Say that in the source file there
is a reference:

\starttyping
foo_Bar_01_03-a.EPS
\stoptyping

and that the graphic on disk has the same name, but for some reason after an
update has become:

\starttyping
foo-Bar_01_03-a.EPS
\stoptyping

The old image is probably still there so the update is not reflected in the final
product. This is not that uncommon when you deal with tens of thousands of files,
many editors and graphic designers, and no strict filename policy.

For this we provide the following tracing option:

\starttyping
\enabletrackers[graphics.lognames]
\stoptyping

This will put information in the log file about included graphics, like:

\starttyping
system          > graphics > start names

used graphic    > asked   : cow.pdf
used graphic    > comment : not found
used graphic    > asked   : t:/sources/cow.pdf
used graphic    > format  : pdf
used graphic    > found   : t:/sources/cow.pdf
used graphic    > used    : t:/sources/cow.pdf

system          > graphics > stop names
\stoptyping

You can also add information to the file itself:

\starttyping
\usemodule[s-figures-names]
\stoptyping

Of course that has to be done at the end of the document. Bad names are reported
and suitable action can be taken.

\stopsection

\startsection[title=Downsampling]

You can plug in you rown converter, here is an example:

\starttyping
\startluacode

figures.converters.jpg = figures.converters.jpg or { }

figures.converters.jpg["lowresjpg.pdf"] =
  function(oldname,newname,resolution)
    figures.programs.run (
      [[gm]],
      [[convert -geometry %nx%x%ny% -compress JPEG "%old%" "%new%"]],
      {
         old = old,
         new = new,
         nx  = resolution or 300,
         ny  = resolution or 300,
      }
    )
  end
\stopluacode
\stoptyping

You can limit the search to a few types and set the resolution with:

\starttyping
\setupexternalfigures
  [order={pdf,jpg},
   resolution=100,
   method=auto]
\stoptyping

And use it like:

\starttyping
\externalfigure[verybig.jpg][height=10cm]
\stoptyping

The second string passed to the \type {run} helper contains the arguments to the
first one. The variables between percent signs get replaced by the variables in
the tables passed as third argument.

\stopsection

\startsection[title=Trackers]

If you want a lot of info you can say:

\starttyping
\enabletrackers[figures.*]
\stoptyping

But you can be more specific. With \type {graphics.locating} you will get some
insight in where files are looked for. The \type {graphics.inclusion} tracker
gives some more info about actual inclusion. The \type {graphics.bases} is kind
of special and only makes sense when you use the graphic database options. The
\type {graphics.conversion} and related tracker \type {graphics.programs} show if
and how conversion of images takes place.

The \type {graphics.lognames} will make sure that some extra information about
used graphics is saved in the log file, The \type {graphics.usage} tracker will
produce a file \typ {<jobname>-figures-usage.lua} that contains information about
found (or not found) images and the way they are used.

\stopsection

\startsection[title=Compression]

A \PNG\ image uses several methods for compression. The image data itself can be
compacted by taking pixels around each individual pixel into account. Storing
deltas instead of absolute values can for instance result in strips of zeros.
These in turn compress well using zlib compression. Each scanline starts with a
filterbyte that indicates how to look at the surrounding pixels. While in \PDF\ a
\JPEG\ image is included as|-|is, a \PNG\ often take a bit more work. A
(optional) mask has to be split off, as does an (optional) index. In the worst
case we need to deinterlace. The \PNG\ inclusion mechanism in \CONTEXT\ \LMTX\
takes care of this in an as efficient as possible way. Nevertheless there are
some knobs you can turn:

\starttyping
\enabledirectives[graphics.png.recompress]
\enabledirectives[graphics.png.compresslevel=9]
\stoptyping

A higher compress level makes the run somewhat smaller but also fives smaller
files. The default compress level is~3. When an image doesn't need to be
transformed (due to mask, index or interlace), you have to force recompression
with the \type {recompress} directive. The sample image \type {mill.png} has a
size of \type {154,869} bytes.

\starttyping
\startTEXpage
    \externalfigure[mill.png]
\stopTEXpage
\stoptyping

The next table shows the consequences of setting the directives. The runtime is
of course dependent of the machine you run the sample on. If you have lots of
images it might make sense to have a final run with a higher compress level. The
\PDF\ file has some extra overhead (like metadata and page related information).

\starttabulate[|l|c|c|c|]
\BC               \BC compression \BC filesize \BC runtime \NC \NR
\BC default       \NC             \NC 156,964  \NC 0.516   \NC \NR
\BC recompress    \NC 3           \NC 144,418  \NC 0.531   \NC \NR
\BC compresslevel \NC 0           \NC 281,071  \NC 0.516   \NC \NR
\BC compresslevel \NC 9           \NC 137,375  \NC 0.547   \NC \NR
\stoptabulate

\stopsection

\startsection[title=Remote]

You can include images from a remote location using a \URL\ specification.

\starttyping
\externalfigure[https://www.pragma-ade.com/logo-ade.png] % via curl
\externalfigure[http://www.pragma-ade.com/logo-ade.png]  % via socket
\stoptyping

Normally the socket library will be used for \type {http} and Curl for \type
{https}. Images are cached and there is some threshold that makes sure that we
don't keep fetching. You can set the threshold to zero seconds to avoid that:

\starttyping
\enabledirectives[schemes.threshold=0]
\stoptyping

In \LMTX\ there are some more options:

\starttyping
\enabledirectives[schemes.inmemory]
\enabledirectives[schemes.uselibrary]
\stoptyping

The first option avoid storing an image in a file and therefore consumes a bit
more memory and the second one tries to use the Curl library instead of calling
the program. If you want ot see what is going on you can use:

\starttyping
\enabletrackers[resolvers.schemes]
\enabletrackers[graphics.locating]
\enabletrackers[resolvers.virtual]
\stoptyping

\stopsection

\stopchapter

\stopcomponent