l3image.dtx

% \iffalse meta-comment
%
%% File: l3image.dtx Copyright(C) 2017 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    http://www.latex-project.org/lppl.txt
%
% This file is part of the "l3trial bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver|package>
\RequirePackage{expl3}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3image} package\\ Image inclusion support^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2017/12/05}
%
% \maketitle
%
% \begin{documentation}
%
% \section{\pkg{l3image} documentation}
%
% \begin{variable}{interpolate}
%   Indicates whether interpolation should be applied to bitmap image files.
%   This key will be ignored for vector image files.
% \end{variable}
%
% \begin{variable}{page}
%   The page number of an image to be used when including a multi-page
%   PDF file as an image. This key will be ignored for non-PDF images.
% \end{variable}
%
% \begin{variable}{pagebox}
%   The page box setting used when determining the bounding box of an image:
%   used for |.pdf| images which may present multiple page boxes. Valid
%   settings are |artbox|, |bleedbox|, |cropbox| (the standard setting),
%   |mediabox| and |trimbox|.
% \end{variable}
%
% \subsection{Internal functions}
%
% Inclusion of image files requires a range of low-level data be passed to
% the driver layer. Individual drivers also require some common routines
% which in themselves contain no driver-specific code. This functionality
% is made available here.
%
% \begin{variable}{\l__image_decode_tl}
%   Array to decode color in bitmap image: when non-empty, this should
%   be in the form of one, two or three pairs of real numbers in the range
%   $[0,1]$, separated by spaces.
% \end{variable}
%
% \begin{variable}{\l__image_interpolate_bool}
%   Indicates whether interpolation should be applied to bitmap image files.
% \end{variable}
%
% \begin{variable}{\l__image_page_int}
%   The page to extract from a multi-page image file: used for |.pdf| files
%   which may contain multiple pages.
% \end{variable}
%
% \begin{variable}{\l__image_pagebox_tl}
%   The nature of the page box setting used to determine the bounding box of
%   material: used for |.pdf| files which feature multiple page box
%   specifications.
% \end{variable}
%
% \begin{variable}
%   {\l__image_llx_dim, \l__image_lly_dim, \l__image_urx_dim, \l__image_ury_dim}
%   Dimensions which return the points $(\meta{llx},\meta{lly})$ and
%   $(\meta{urx},\meta{ury})$ for the image. For many images only the resulting
%   height and width are significant, but this is driver-dependent.
% \end{variable}
%
% \begin{function}{\__image_extract_bb:n}
%   \begin{syntax}
%     \cs{__image_extract_bb:n} \meta{file}
%   \end{syntax}
%   Extracts bounding box data for the image \meta{file} using the |extractbb|
%   utility, and stores the bounding box of the image file in
%   \cs{l__image_llx_dim}, \cs{l__image_lly_dim}, \cs{l__image_urx_dim} and
%   \cs{l__image_ury_dim}.
%
%   The \meta{file} name should be fully-qualified and sanitized: no search
%   or other manipulation is carried out at this level. No check is made on
%   the file \emph{type} at this stage: it is assumed that the driver code
%   using this function has made such a check. File types such as |.pdf| and
%   |.jpg| are appropriate for parsing using this function.
%
%   When \cs{l__image_page_int} is positive the appropriate page will be
%   queried from the image file.
%
%   Note that this function requires pipe shell calls to be enabled: this is
%   generally true but may require the option |--enable-pipes| to be enabled
%   when running the \TeX{} job.
% \end{function}
%
% \begin{function}{\__image_read_bb:n}
%   \begin{syntax}
%     \cs{__image_read_bb:n} \meta{file}
%   \end{syntax}
%   Parses the image \meta{file} to find a PostScript-style bounding box
%   line of the form
%   \begin{verbatim}
%   %%BoundingBox: llx lly urx urx
%   \end{verbatim}
%   where \meta{llx}, \meta{lly}, \meta{urx} and \meta{ury} are the corners
%   of the bounding box expressed in PostScript (\enquote{big}) points. The
%   values are stored in \cs{l__image_llx_dim}, \cs{l__image_lly_dim},
%   \cs{l__image_urx_dim} and \cs{l__image_ury_dim}.
%
%   The \meta{file} name should be fully-qualified and sanitized: no search
%   or other manipulation is carried out at this level. No check is made on
%   the file \emph{type} at this stage: it is assumed that the driver code
%   using this function has made such a check. File types such as |.eps| and
%   |.bb|/|.xbb| are appropriate for parsing using this function.
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3image} implementation}
%
%    \begin{macrocode}
%<*initex|package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=image>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage{l3image}{2017/12/05}{}
  {L3 Experimental image inclusion support}
%</package>
%    \end{macrocode}
%
% \begin{variable}{\l_@@_tmp_ior, \l_@@_tmp_tl}
%   Scratch space.
%    \begin{macrocode}
\ior_new:N \l_@@_tmp_ior
\tl_new:N  \l_@@_tmp_tl
%    \end{macrocode}
% \end{variable}
%
% \subsection{Image feature support}
%
% \begin{macro}
%   {
%     \l__image_decode_tl       ,
%     \l__image_interpolate_bool,
%     \l__image_page_int        ,
%     \l__image_pagebox_tl
%   }
%   Keys which control features of images. The standard value of |[pagebox|
%   set up here should match the default for the drivers themselves: in
%   the absence of any other setting the |cropbox| should be used.
%    \begin{macrocode}
\tl_new:N \l__image_pagebox_tl
\keys_define:nn { image }
  {
    decode      .tl_set:N   = \l__image_decode_tl        ,
    interpolate .bool_set:N = \l__image_interpolate_bool ,
    page        .int_set:N  = \l__image_page_int         ,
    pagebox     .choices:nn =
      { artbox , bleedbox , cropbox , mediabox , trimbox }
      { \tl_set:Nn \l__image_pagebox_tl {#1} },
    pagebox     .initial:n  = cropbox
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Obtaining bounding box data}
%
% \begin{variable}
%   {
%     \l__image_llx_dim , \l__image_lly_dim,
%     \l__image_urx_dim , \l__image_ury_dim
%   } 
%   Storage for the return of bounding box.
%    \begin{macrocode}
\dim_new:N \l__image_llx_dim
\dim_new:N \l__image_lly_dim
\dim_new:N \l__image_urx_dim
\dim_new:N \l__image_ury_dim
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\__image_extract_bb:n, \__image_read_bb:n}
% \begin{macro}{\@@_extract_bb_auix:nn, \@@_extract_bb_auix:Vn}
% \begin{macro}{\@@_extract_bb_auxii:nnn}
% \begin{macro}{\@@_extract_bb_auxiii:nnnn, \@@_extract_bb_auxiii:Vnnn}
% \begin{macro}{\@@_extract_bb_auxiv:nnn}
% \begin{macro}{\@@_read_bb_auxi:nnnn, \@@_read_bb_auxii:Vnnn}
% \begin{macro}
%   {
%     \@@_read_bb_auxii:w ,
%     \@@_read_bb_auxiv:w ,
%     \@@_read_bb_auxv:w
%   }
%  Extracting the bounding box from an |.eps| or |.bb| file is done by
%  reading each line and searching for the marker text |%%BoundingBox:|.
%  The data is read as a string with a mapping over
%  the lines: as there is a colon involved, a little bit of work is needed to
%  get the matching correct. The same approach covers cases where the bounding
%  box has to be calculated by |extractbb|, with just the initial phase
%  different.
%    \begin{macrocode}
\cs_new_protected:Npn \__image_extract_bb:n #1
  {
    \int_compare:nNnTF \l__image_page_int > 0
      { \@@_extract_bb_auxi:Vn \l__image_page_int {#1} }
      { \@@_extract_bb_auxii:nnn {#1} { } { } }
  }
\cs_new_protected:Npn \@@_extract_bb_auxi:nn #1#2
  { \@@_extract_bb_auxii:nnn {#2} { :P #1 } { -p~#1~ } }
\cs_generate_variant:Nn \@@_extract_bb_auxi:nn { Vn }
\cs_new_protected:Npn \@@_extract_bb_auxii:nnn #1#2#3
  {
   \tl_if_empty:NTF \l__image_pagebox_tl
      { \@@_extract_bb_auxiv:nnn }
      { \@@_extract_bb_auxiii:Vnnn \l__image_pagebox_tl }
      {#1} {#2} {#3}
  }
\cs_new_protected:Npn \@@_extract_bb_auxiii:nnnn #1#2#3#4
  { \@@_extract_bb_auxiv:nnn {#2} { : #1 #3 } { #4 -B~#1~ } }
\cs_generate_variant:Nn \@@_extract_bb_auxiii:nnnn { V }
\cs_new_protected:Npn \@@_extract_bb_auxiv:nnn #1#2#3
  {
    \@@_read_bb_auxi:nnnn {#1} {#2}
      { \tex_openin:D \l_@@_tmp_ior = "|extractbb~#3-O~#1" }
      { pipe-failed }
  }
\cs_new_protected:Npn \__image_read_bb:n #1
  {
    \@@_read_bb_auxi:nnn {#1} { }
      { \ior_open:Nn \l_@@_tmp_ior {#1} }
      { image-not-found }
  }
%   \end{macrocode}
%  Before any real searching, a check to see if there are cached values
%  available. The name of each image will be unique and so it's sensible to
%  store the bounding box data in \TeX{}: this avoids multiple file operations.
%  As bounding boxes here start away from the lower-left origin, we need to
%  store all four values (contrast with for example the \texttt{pdfmode}
%  driver). Here |#2| is a potential page identifier: used to allow caching of
%  individual pages in a multi-page document. Caching is applied to the
%  upper-right position in all cases, but as the lower-left will often be
%  $(0,0)$ it is only cached if required.
%   \begin{macrocode}
\cs_new_protected:Npn \@@_read_bb_auxi:nnnn #1#2#3#4
  {
    \dim_if_exist:cTF { c_@@_ #1#2 _urx_dim }
      {
        \dim_set_eq:Nc \l__image_urx_dim { c_@@_ #1#2 _urx_dim }
        \dim_set_eq:Nc \l__image_ury_dim { c_@@_ #1#2 _ury_dim }
        \dim_if_exist:cTF { c_@@_ #1#2 _llx_dim }
          { \dim_set_eq:Nc \l__image_llx_dim { c_@@_ #1#2 _llx_dim } }
          { \dim_zero:N \l__image_urx_dim }
        \dim_if_exist:cTF { c_@@_ #1#2 _lly_dim }
          { \dim_set_eq:Nc \l__image_lly_dim { c_@@_ #1#2 _lly_dim } }
          { \dim_zero:N \l__image_lly_dim }
      }
      { \@@_read_bb_auxii:nnn {#3} {#4} {#1} {#2} }
  }
\cs_new_protected:Npx \@@_read_bb_auxii:nnnn #1#2#3#4
  {
    #3
    \exp_not:N \ior_if_eof:NTF \exp_not:N \l_@@_tmp_ior
      { \__msg_kernel_error:nnn { kernel } {#2} {#3} }
      {
        \ior_str_map_inline:Nn \exp_not:N \l_@@_tmp_ior
          {
            \exp_not:N \@@_image_read_bb_auxiii:w
              ##1 ~ \c_colon_str \exp_not:N \q_stop
          }
      }
    \exp_not:n
      {
        \ior_close:N \exp_not:N \l_@@_tmp_ior
        \dim_compare:nNnF \l__image_llx_dim = { 0pt }
          { \dim_const:cn { c_@@_ #3#4 _llx_dim } { \l__image_llx_dim } }
        \dim_if_zero:nNnF \l__image_lly_dim = { 0pt }
          { \dim_const:cn { c_@@_ #3#4 _lly_dim } { \l__image_lly_dim } }
        \dim_const:cn { c_@@_ #3#4 _urx_dim } { \l__image_urx_dim }
        \dim_const:cn { c_@@_ #3#4 _ury_dim } { \l__image_ury_dim }
      }
  }
\use:x
  {
    \cs_new_protected:Npn \exp_not:N \@@_read_bb_auxiii:w
      ##1 \c_colon_str ##2 \exp_not:N \q_stop
      {
        \exp_not:N \str_if_eq:nnT
          { \c_percent_str \c_percent_str BoundingBox }
          {##1}
          { \exp_not:N \@@_read_bb_auxiv:w ##2 ( ) \exp_not:N \q_stop }
      }
  }
%    \end{macrocode}
%   If the bounding box is |atend|, just ignore the current one and keep going.
%   Otherwise, we need to allow for tabs and multiple spaces (as the line has
%   been read as a string). The easiest way to deal with that is to scan the
%   tokens: at this stage the line fragment should be just numbers and
%   whitespace. \TeX{} will then tidy up for us, with just a leading space to
%   worry about: that is taken out by the |\use:n| here.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_read_bb_auxiv:w #1 ( #2 ) #3 \q_stop
  {
    \str_if_eq:nnF {#2} { atend }
      {
        \tl_set_rescan:Nnx \l_@@_tmp_tl
          {
            \char_set_catcode_space:n {  9 }
            \char_set_catcode_space:n { 32 }
          }
          { \use:n #1 }
        \exp_after:wN \@@_read_bb_auxv:w \l_@@_tmp_tl \q_stop
      }
  }
%    \end{macrocode}
%   A trailing space was deliberately added earlier so we know that the final
%   data point is terminated by a space.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_read_bb_auxv:w #1~#2~#3~#4~#5 \q_stop
  {
    \dim_set:Nn \l__image_llx_dim { #1 bp }
    \dim_set:Nn \l__image_lly_dim { #2 bp }
    \dim_set:Nn \l__image_urx_dim { #3 bp }
    \dim_set:Nn \l__image_ury_dim { #4 bp }
    \ior_map_break:
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Messages}
%
%    \begin{macrocode}
\__msg_kernel_new:nnnn { image } { image-not-found }
  { Image~file~'#1'~not~found. }
  {
    LaTeX~tried~to~open~image~file~'#1',
    ~but~the~file~could~not~be~read.
  }
\__msg_kernel_new:nnnn { image } { pipe-failed }
  { Cannot~run~piped~system~commands. }
  {
    LaTeX~tried~to~call~a~system~process~but~this~was~not~possible.\\
    Try~the~"--shell-escape"~(or~"--enable-pipes")~option.
  }
%    \end{macrocode}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex