| 1 | # /=====================================================================\ # | ||
| 2 | # | LaTeXML::Post::Graphics | # | ||
| 3 | # | Graphics postprocessing for LaTeXML | # | ||
| 4 | # |=====================================================================| # | ||
| 5 | # | Part of LaTeXML: | # | ||
| 6 | # | Public domain software, produced as part of work done by the | # | ||
| 7 | # | United States Government & not subject to copyright in the US. | # | ||
| 8 | # |---------------------------------------------------------------------| # | ||
| 9 | # | Bruce Miller <bruce.miller@nist.gov> #_# | # | ||
| 10 | # | http://dlmf.nist.gov/LaTeXML/ (o o) | # | ||
| 11 | # \=========================================================ooo==U==ooo=/ # | ||
| 12 | #====================================================================== | ||
| 13 | # Adapted from graphics-support.perl of LaTeX2HTML (which I had rewritten) | ||
| 14 | #====================================================================== | ||
| 15 | package LaTeXML::Post::Graphics; | ||
| 16 | use strict; | ||
| 17 | use warnings; | ||
| 18 | use LaTeXML::Util::Pathname; | ||
| 19 | use LaTeXML::Util::Image; | ||
| 20 | use LaTeXML::Post; | ||
| 21 | use base qw(LaTeXML::Post::Processor); | ||
| 22 | |||
| 23 | #====================================================================== | ||
| 24 | # Options: | ||
| 25 | # DPI : dots per inch for target medium. | ||
| 26 | # ignore_options : list of graphicx options to be ignored. | ||
| 27 | # warn_options : list of graphicx options to cause warning if used. | ||
| 28 | # trivial_scaling : If true, web images that only need scaling will be used as-is | ||
| 29 | # assuming the user agent scale the image. | ||
| 30 | # background : background color when filling or transparency. | ||
| 31 | # type_properties : hash of types=>hash. | ||
| 32 | # The hash for each type can have the following | ||
| 33 | # destination_type : the type to convert the file to if different. | ||
| 34 | # transparent : if true, the background color will be made transparent. | ||
| 35 | # quality : the `quality' used for the image. | ||
| 36 | # ncolors : the image will be quantized to ncolors. | ||
| 37 | # prescale : If true, and there are leading (or only) scaling commands, | ||
| 38 | # compute the new image size and re-read the image into that size | ||
| 39 | # This is useful for getting the best antialiasing for postscript, eg. | ||
| 40 | # unit= (pixel|point) : What unit the image size is given in. | ||
| 41 | # autocrop : if the image should be cropped (trimmed) when loaded. | ||
| 42 | # desirability : a number indicating how good of a mapping this entry is. | ||
| 43 | # This helps choose between two sources that can map to the | ||
| 44 | # same destination type. | ||
| 45 | # An entry whose source & destination types are the same | ||
| 46 | # has desirability=10. | ||
| 47 | |||
| 48 | sub new { | ||
| 49 | my ($class, %options) = @_; | ||
| 50 | my $self = $class->SUPER::new(%options); | ||
| 51 | $$self{DPI} = $options{DPI}; | ||
| 52 | $$self{ignore_options} = $options{ignore_options} || []; | ||
| 53 | $$self{trivial_scaling} = $options{trivial_scaling} || 1; | ||
| 54 | $$self{graphics_types} = $options{graphics_types} | ||
| 55 | || [qw(svg png gif jpg jpeg | ||
| 56 | eps ps postscript ai pdf)]; | ||
| 57 | $$self{type_properties} = $options{type_properties} | ||
| 58 | || { | ||
| 59 | ai => { destination_type => 'png', | ||
| 60 | transparent => 1, | ||
| 61 | prescale => 1, ncolors => '400%', quality => 90, unit => 'point' }, | ||
| 62 | pdf => { destination_type => 'png', | ||
| 63 | transparent => 1, | ||
| 64 | prescale => 1, ncolors => '400%', quality => 90, unit => 'point' }, | ||
| 65 | ps => { destination_type => 'png', transparent => 1, | ||
| 66 | prescale => 1, ncolors => '400%', quality => 90, unit => 'point' }, | ||
| 67 | eps => { destination_type => 'png', transparent => 1, | ||
| 68 | prescale => 1, ncolors => '400%', quality => 90, unit => 'point' }, | ||
| 69 | jpg => { destination_type => 'jpg', | ||
| 70 | ncolors => '400%', unit => 'pixel' }, | ||
| 71 | jpeg => { destination_type => 'jpeg', | ||
| 72 | ncolors => '400%', unit => 'pixel' }, | ||
| 73 | gif => { destination_type => 'gif', transparent => 1, | ||
| 74 | ncolors => '400%', unit => 'pixel' }, | ||
| 75 | png => { destination_type => 'png', transparent => 1, | ||
| 76 | ncolors => '400%', unit => 'pixel' }, | ||
| 77 | svg => { destination_type => 'svg', | ||
| 78 | raster => 0, desirability => 11 }, # use these, as is | ||
| 79 | }; | ||
| 80 | $$self{background} = $options{background} || "#FFFFFF"; | ||
| 81 | return $self; } | ||
| 82 | |||
| 83 | # Return a list of XML nodes which have graphics that need processing. | ||
| 84 | sub toProcess { | ||
| 85 | my ($self, $doc) = @_; | ||
| 86 | return $doc->findnodes('//ltx:graphics[not(@imagesrc)]'); } | ||
| 87 | |||
| 88 | sub process { | ||
| 89 | my ($self, $doc, @nodes) = @_; | ||
| 90 | local $LaTeXML::Post::Graphics::SEARCHPATHS | ||
| 91 | = [map { pathname_canonical($_) } $self->findGraphicsPaths($doc), $doc->getSearchPaths]; | ||
| 92 | Debug(" [Using graphicspaths: " | ||
| 93 | . join(', ', @$LaTeXML::Post::Graphics::SEARCHPATHS) . "]") if $LaTeXML::DEBUG{images}; | ||
| 94 | foreach my $node (@nodes) { | ||
| 95 | $self->processGraphic($doc, $node); } | ||
| 96 | $doc->closeCache; # If opened. | ||
| 97 | return $doc; } | ||
| 98 | |||
| 99 | # Need a proper API to query PI's, probably in Post | ||
| 100 | # But Core isn't respecting @at@document@begin from preloaded packages, | ||
| 101 | # so here we're testing BOTH a straight DPI PI and the options from latexml.sty (ugh) | ||
| 102 | sub getParameter { | ||
| 103 | my ($self, $doc, $parameter) = @_; | ||
| 104 | my $value; | ||
| 105 | foreach my $pi (@{ $$doc{processingInstructions} }) { | ||
| 106 | if ($pi =~ /^\s*$parameter\s*=\s*([\"\'])(.*?)\1\s*$/) { | ||
| 107 | $value = $2; } | ||
| 108 | elsif ($pi =~ /^\s*package\s*=\s*([\"\'])latexml\1\s*options\s*=\s*([\"\'])(.*?)\2\s*$/i) { | ||
| 109 | my $options = $3; | ||
| 110 | if ($options =~ /\b$parameter\s*=\s*(\d+)\b/i) { | ||
| 111 | $value = $1; } } } | ||
| 112 | return $value || $$self{$parameter}; } | ||
| 113 | |||
| 114 | #====================================================================== | ||
| 115 | # Potentially customizable operations. | ||
| 116 | # find graphics file | ||
| 117 | # Need to deal with source directory, as well as graphicspath. | ||
| 118 | |||
| 119 | # Extract any graphicspath PI's from the document and return a reference | ||
| 120 | # to a list of search paths. | ||
| 121 | sub findGraphicsPaths { | ||
| 122 | my ($self, $doc) = @_; | ||
| 123 | my @paths = (); | ||
| 124 | foreach my $pi ($doc->findnodes('.//processing-instruction("latexml")')) { | ||
| 125 | if ($pi->textContent =~ /^\s*graphicspath\s*=\s*([\"\'])(.*?)\1\s*$/) { | ||
| 126 | push(@paths, $2); } } | ||
| 127 | return @paths; } | ||
| 128 | |||
| 129 | sub getGraphicsSourceTypes { | ||
| 130 | my ($self) = @_; | ||
| 131 | return @{ $$self{graphics_types} }, map { uc($_); } @{ $$self{graphics_types} }; } | ||
| 132 | |||
| 133 | # Return the pathname to an appropriate image. | ||
| 134 | sub findGraphicFile { | ||
| 135 | my ($self, $doc, $node) = @_; | ||
| 136 | if (my $source = $node->getAttribute('graphic')) { | ||
| 137 | # if we already have a usable candidate, save ourselves the work | ||
| 138 | my @paths = grep { -e $_ } split(',', $node->getAttribute('candidates') || ''); | ||
| 139 | if (!scalar(@paths)) { | ||
| 140 | # Find all acceptable image files, in order of search paths | ||
| 141 | my ($dir, $name, $reqtype) = pathname_split($source); | ||
| 142 | # Ignore the requested type? Or should it increase desirability? | ||
| 143 | # | ||
| 144 | # If this is *NOT* a known graphics type, it would be best to treat it as | ||
| 145 | # a name suffix (e.g. name.1 from name.1.png) | ||
| 146 | if ((length($reqtype) > 0) && !(grep { $_ eq lc($reqtype) } $$self{graphics_types})) { | ||
| 147 | $name .= ".$reqtype"; } | ||
| 148 | my $file = pathname_concat($dir, $name); | ||
| 149 | @paths = pathname_findall($file, paths => $LaTeXML::Post::Graphics::SEARCHPATHS, | ||
| 150 | # accept empty type, incase bad type name, but actual file's content is known type. | ||
| 151 | types => ['', $self->getGraphicsSourceTypes]); | ||
| 152 | } | ||
| 153 | my ($best, $bestpath) = (-1, undef); | ||
| 154 | # Now, find the first image that is either the correct type, | ||
| 155 | # or has the most desirable type mapping | ||
| 156 | foreach my $path (@paths) { | ||
| 157 | my $type = pathname_type($path); | ||
| 158 | my $props = $$self{type_properties}{$type}; | ||
| 159 | my $desirability = $$props{desirability} || ($type eq ($$props{destination_type} || 'notype') ? 10 : 0); | ||
| 160 | if ($desirability > $best) { | ||
| 161 | $best = $desirability; | ||
| 162 | $bestpath = $path; } } | ||
| 163 | return $bestpath; } | ||
| 164 | else { | ||
| 165 | return; } } | ||
| 166 | |||
| 167 | #====================================================================== | ||
| 168 | # Return the Transform to be used for this node | ||
| 169 | # Default is based on parsing the graphicx options | ||
| 170 | sub getTransform { | ||
| 171 | my ($self, $node) = @_; | ||
| 172 | my $options = $node->getAttribute('options'); | ||
| 173 | return ($options ? image_graphicx_parse($options) : []); } | ||
| 174 | |||
| 175 | # Get a hash of the image processing properties to be applied to this image. | ||
| 176 | sub getTypeProperties { | ||
| 177 | my ($self, $source, $options) = @_; | ||
| 178 | my ($dir, $name, $ext) = pathname_split($source); | ||
| 179 | my $props = $$self{type_properties}{ lc($ext) }; | ||
| 180 | if (!$props) { | ||
| 181 | # If we don't have a known file type, try a bit harder (maybe less efficient) | ||
| 182 | if (my $type = image_type($source)) { | ||
| 183 | $props = $$self{type_properties}{ lc($type) }; } } | ||
| 184 | return ($props ? %$props : ()); } | ||
| 185 | |||
| 186 | # Set the attributes of the graphics node to record the image file name, | ||
| 187 | # width and height. | ||
| 188 | sub setGraphicSrc { | ||
| 189 | my ($self, $node, $src, $width, $height) = @_; | ||
| 190 | # If we are on windows, the $src path will be used for a URI context from the 'imagesrc' attribute, | ||
| 191 | # so we can already switch it to the canonical slashified form | ||
| 192 | $node->setAttribute('imagesrc', pathname_to_url($src)); | ||
| 193 | if (defined $width) { | ||
| 194 | # final formats mostly expect numeric literals to be integers | ||
| 195 | $width = int($width) if ($width =~ /^\d*\.\d*$/); | ||
| 196 | $node->setAttribute('imagewidth', $width); } | ||
| 197 | if (defined $height) { | ||
| 198 | # final formats mostly expect numeric literals to be integers | ||
| 199 | $height = int($height) if ($height =~ /^\d*\.\d*$/); | ||
| 200 | $node->setAttribute('imageheight', $height); } | ||
| 201 | if ($width and $height) { | ||
| 202 | my $aspect_class = "ltx_img_square"; | ||
| 203 | if ($width > 1.24 * $height) { | ||
| 204 | $aspect_class = "ltx_img_landscape"; } | ||
| 205 | elsif ($height > 1.24 * $width) { | ||
| 206 | $aspect_class = "ltx_img_portrait" } | ||
| 207 | my $class = $node->getAttribute('class'); | ||
| 208 | $class = ($class ? $class . ' ' : '') . $aspect_class; | ||
| 209 | $node->setAttribute('class', $class); } | ||
| 210 | return; } | ||
| 211 | |||
| 212 | sub processGraphic { | ||
| 213 | my ($self, $doc, $node) = @_; | ||
| 214 | my $source = $self->findGraphicFile($doc, $node); | ||
| 215 | if (!$source) { | ||
| 216 | Warn('expected', 'source', $node, "No graphic source found; skipping", | ||
| 217 | "source was " . ($node->getAttribute('graphic') || 'none')); | ||
| 218 | $node->setAttribute('imagesrc', $node->getAttribute('graphic')); | ||
| 219 | return; } | ||
| 220 | my $transform = $self->getTransform($node); | ||
| 221 | my ($image, $width, $height) = $self->transformGraphic($doc, $node, $source, $transform); | ||
| 222 | # $image should probably be relative already, except corner applications? | ||
| 223 | # But definitely should be stored in doc relative to the doc itself! | ||
| 224 | $self->setGraphicSrc($node, pathname_relative($image, $doc->getDestinationDirectory), | ||
| 225 | $width, $height) if $image; | ||
| 226 | return; } | ||
| 227 | |||
| 228 | #====================================================================== | ||
| 229 | |||
| 230 | sub transformGraphic { | ||
| 231 | my ($self, $doc, $node, $source, $transform) = @_; | ||
| 232 | my @parameters = ( | ||
| 233 | DPI => $self->getParameter($doc, 'DPI') || $LaTeXML::Util::Image::DPI, | ||
| 234 | magnify => $self->getParameter($doc, 'magnify'), | ||
| 235 | upsample => $self->getParameter($doc, 'upsample'), | ||
| 236 | zoomout => $self->getParameter($doc, 'zoomout')); | ||
| 237 | my $sourcedir = $doc->getSourceDirectory; | ||
| 238 | ($sourcedir) = $doc->getSearchPaths unless $sourcedir; # Fishing... | ||
| 239 | my ($reldir, $name, $srctype) | ||
| 240 | = pathname_split(pathname_relative($source, $sourcedir)); | ||
| 241 | my %properties = $self->getTypeProperties($source, $transform); | ||
| 242 | return Warn('unexpected', 'graphics_format', undef, | ||
| 243 | "Don't know what to do with graphics file format '$source'") unless %properties; | ||
| 244 | my $type = $properties{destination_type} || $srctype; | ||
| 245 | my $key = (ref $self) . ':' . join('|', "$reldir$name.$srctype.$type", | ||
| 246 | map { join(' ', @$_) } @$transform); | ||
| 247 | Debug("Processing $source as key=$key") if $LaTeXML::DEBUG{images}; | ||
| 248 | |||
| 249 | my $dest = $self->desiredResourcePathname($doc, $node, $source, $type); | ||
| 250 | if (my $prev = $doc->cacheLookup($key)) { # Image was processed on previous run? | ||
| 251 | if ($prev =~ /^(.*?)\|(\d*)\|(\d*)$/) { | ||
| 252 | my ($cached, $width, $height) = ($1, $2, $3); | ||
| 253 | $width = undef unless $width; | ||
| 254 | $height = undef unless $height; | ||
| 255 | # If so, check that it is still there, up to date, etc. | ||
| 256 | if ((!defined $dest) || ($cached eq $dest)) { | ||
| 257 | my $absdest = pathname_absolute($cached, $doc->getDestinationDirectory); | ||
| 258 | if (pathname_timestamp($source) <= pathname_timestamp($absdest)) { | ||
| 259 | Debug(" [Reuse $cached @ " . ($width || '?') . " x " . ($height || '?') . "]") | ||
| 260 | if $LaTeXML::DEBUG{images}; | ||
| 261 | return ($cached, $width, $height); } } } } | ||
| 262 | # Trivial scaling case: Use original image with (at most) different width & height. | ||
| 263 | my $triv_scaling = $$self{trivial_scaling} && ($type eq $srctype) | ||
| 264 | && image_graphicx_is_trivial($transform); | ||
| 265 | # But first check if we have the capabilities to do complex scaling! | ||
| 266 | if (!$triv_scaling && (defined $properties{raster}) && !$properties{raster}) { | ||
| 267 | Warn("limitation", $source, undef, | ||
| 268 | "Cannot (yet) apply complex transforms to non-raster images", | ||
| 269 | join(',', map { join(' ', @$_) } grep { !($_->[0] =~ /^scale/) } @$transform)); | ||
| 270 | $triv_scaling = 1; | ||
| 271 | $transform = image_graphicx_trivialize($transform); } | ||
| 272 | if (!image_can_image()) { | ||
| 273 | if ($type ne $srctype) { | ||
| 274 | Error('imageprocessing', 'imageclass', undef, | ||
| 275 | "No image processing module found to convert types", | ||
| 276 | "Skipping $source=>$type.", | ||
| 277 | "Please install one of: " . join(',', image_classes())); | ||
| 278 | return; } | ||
| 279 | elsif (!$triv_scaling) { | ||
| 280 | Error('imageprocessing', 'imageclass', undef, | ||
| 281 | "No image processing module found for complex transformations", | ||
| 282 | "Simplifying transformation of $source.", | ||
| 283 | "Please install one of: " . join(',', image_classes())); | ||
| 284 | $triv_scaling = 1; | ||
| 285 | $transform = image_graphicx_trivialize($transform); } | ||
| 286 | } | ||
| 287 | my ($image, $width, $height); | ||
| 288 | if ($triv_scaling) { | ||
| 289 | # With a simple scaling transformation we can preserve path & file-names | ||
| 290 | # But only if we can mimic the relative path in the site directory. | ||
| 291 | # Get image source file relative to the document's source file | ||
| 292 | $dest = pathname_relative($source, $doc->getSourceDirectory); | ||
| 293 | # and it's (eventual) absolute path in the destination directory | ||
| 294 | # assuming it had the same relative path from the destination file. | ||
| 295 | my $absdest = pathname_absolute($dest, $doc->getDestinationDirectory); | ||
| 296 | # Now IFF that is a valid relative path WITHIN the site directory, we'll use it. | ||
| 297 | # Otherwise, we'd better fall back to a generated name. | ||
| 298 | if (!pathname_is_contained($absdest, $doc->getSiteDirectory)) { | ||
| 299 | $dest = $self->generateResourcePathname($doc, $node, $source, $type); | ||
| 300 | $absdest = $doc->checkDestination($dest); } | ||
| 301 | |||
| 302 | Debug(" [Destination $absdest]") if $LaTeXML::DEBUG{images}; | ||
| 303 | ($width, $height) = image_graphicx_trivial($source, $transform, @parameters); | ||
| 304 | if (!($width && $height)) { | ||
| 305 | if (!image_can_image()) { | ||
| 306 | Warn('imageprocessing', 'imagesize', undef, | ||
| 307 | "No image processing module found for image sizing", | ||
| 308 | "Will omit image size for $source", | ||
| 309 | "Please install one of: " . join(',', image_classes())); } | ||
| 310 | else { | ||
| 311 | Warn('expected', 'image', undef, | ||
| 312 | "Couldn't get usable image size for $source"); } } | ||
| 313 | pathname_copy($source, $absdest) | ||
| 314 | or Warn('I/O', $absdest, undef, "Couldn't copy $source to $absdest", "Response was: $!"); | ||
| 315 | Debug(" [Copied to $dest @ " . ($width || '?') . " x " . ($height || '?') . "]") | ||
| 316 | if $LaTeXML::DEBUG{images}; } | ||
| 317 | else { | ||
| 318 | # With a complex transformation, we really needs a new name (well, don't we?) | ||
| 319 | $dest = $self->generateResourcePathname($doc, $node, $source, $type) unless $dest; | ||
| 320 | my $absdest = $doc->checkDestination($dest); | ||
| 321 | Debug(" [Destination $absdest]") if $LaTeXML::DEBUG{images}; | ||
| 322 | ($image, $width, $height) = image_graphicx_complex($source, $transform, | ||
| 323 | @parameters, background => $$self{background}, %properties); | ||
| 324 | if (!($image && $width && $height)) { | ||
| 325 | Warn('expected', 'image', undef, | ||
| 326 | "Couldn't get usable image for $source"); | ||
| 327 | return; } | ||
| 328 | Debug(" [Writing to $absdest]") if $LaTeXML::DEBUG{images}; | ||
| 329 | image_write($image, $absdest) or return; } | ||
| 330 | |||
| 331 | $doc->cacheStore($key, "$dest|" . ($width || '') . '|' . ($height || '')); | ||
| 332 | Debug(" [done with $key]") if $LaTeXML::DEBUG{images}; | ||
| 333 | return ($dest, $width, $height); } | ||
| 334 | |||
| 335 | #====================================================================== | ||
| 336 | 1; |