Syntax for specifying image size

[jgm]

Googlecode Issue #29

There is currently no way to specify the size of an image.
For some ideas, see http://code.google.com/p/pandoc/wiki/ImageSizes.

[jgm]

Comment 2 by [email protected], Nov 10, 2010
You can enter the dimensions of an image in the header of the JPG or PNG files. LaTeX and the DocBook processors will use that size. In HTML output you can set the size for every image in a separate CSS file.

[candlerb]

Duplicate of #61 ?

[seanfarley]

I'd like to say for the record that all of the advice for image manipulation (see above) doesn't help at all when dealing with vector image formats (svg, TikZ, pdf, etc.). This issue is quite the wrench.

[pckujawa]

@jgm mentions that

You can enter the dimensions of an image in the header of the JPG or PNG files.

I'm not sure what that means. Where does one specify the header of one of these image files? I assume this isn't in reference to the bytes of the image file itself.

[jgm]

+++ pckujawa [Apr 22 13 00:53 ]:

[1]@jgm mentions that

 You can enter the dimensions of an image in the header of the JPG or
 PNG files.

I'm not sure what that means. Where does one specify the header of one
of these image files? I assume this isn't in reference to the bytes of
the image file itself.

The DPI is stored in metadata in the header of the image files.
You can view and manipulate it with most image manipulation programs
(e.g. Gimp, Photoshop). I like to use ImageMagick command line tools,
myself.

convert -units PixelsPerInch my.jpg -density 300 my.new.jpg

[pckujawa]

Ah, so you were referring to the bytes in the image file itself. That
method doesn't let me specify a width that is larger than, for example, the
\maxwidth of the latex page, but I guess that is by design (otherwise
things overflow badly).

For anyone else using latex, I did find that \includegraphics does not work
as expected because the default template has the following remapping:

$if(graphics)$
\usepackage{graphicx}
% We will generate all images so they have a width \maxwidth. This means
% that they will get their normal width if they fit onto the page, but
% are scaled down if they would overflow the margins.
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth
\else\Gin@nat@width\fi}
\makeatother
\let\Oldincludegraphics\includegraphics
\renewcommand{\includegraphics}[1]{\Oldincludegraphics[width=\maxwidth]{#1}}
$endif$

So if you want to use latex and \includegraphics[width=...], you need to
comment out the \renewcommand. Just curious, is there no way to pass
arguments into the [] part of a macro in latex? If there is, why not allow
users to pass in their own [width=...] without having to edit the template?
I'm a newbie to latex macros, so maybe I just don't understand their
complexity.

Thanks for pandoc!
Pat

On Mon, Apr 22, 2013 at 9:43 AM, John MacFarlane - [email protected]
github.pck.374cd93cd6.notifications#[email protected] wrote:

+++ pckujawa [Apr 22 13 00:53 ]:

[1]@jgm mentions that

You can enter the dimensions of an image in the header of the JPG or
PNG files.

I'm not sure what that means. Where does one specify the header of one
of these image files? I assume this isn't in reference to the bytes of
the image file itself.

The DPI is stored in metadata in the header of the image files.
You can view and manipulate it with most image manipulation programs
(e.g. Gimp, Photoshop). I like to use ImageMagick command line tools,
myself.

convert -units PixelsPerInch my.jpg -density 300 my.new.jpg

—
Reply to this email directly or view it on GitHubhttps://issues/261#issuecomment-16795811
.

[adityam]

From what I understand, there is no consensus on markdown syntax to specify the width of an image. For that reason, width specifications are not supported.

[adityam]

Similar to HTML+CSS, ConTeXt allows you to specify the dimensions of individual figures. You can create a figures.tex file:

\defineexternalfigure[filename.ext][width=..., height=...]
\defineexternalfigure[filename.ext][width=..., height=...]

Then generate a ConTeXt file using

pandoc -t context -s output.tex

and compile it using

context --environment=figures.tex output.tex

[pckujawa]

@adityam Thanks, good to know.

[nichtich]

Just a note: if image size should be specified in Pandoc Markdown, one must be able to specify at least two kinds of sizes: first the size in cm or inch for PDF, DocBook, Word etc. and second the size in pixels for HTML, EPUB and related output formats. For bitmap image files both can also be specified in the image files but vector image files usually contain no pixel dimensions.

[mb21]

A TeX hack to get floating images in ConTeXt is to redifine \externalfigure:

\let\externalfigureOrig\externalfigure
\def\externalfigure[#1]{\placefigure[right]{}{\externalfigureOrig[#1]}}

[adityam]

This issue is about changing figure size, and not its floating behavior. By default,

 $pandoc -t context 
 ![Caption](cow.pdf)

gives

\placefigure[here,nonumber]{Caption}{\externalfigure[cow.pdf]}

Do you want to change the floating behavior (from here which floats only when necessary) to right? If so, a better way might be to modify pandoc to generate

\placefigure{Caption}{\externalfigure[cow.pdf]}

and set the default floating behaviour using \setupfloat[figure][location={....}].

[jgm]

I just discovered that in HTML you can do

<img style="width: 3cm;"...>

This resolves the problem about how to convert between pixels and other measurements; we'll just let the browser handle that.

[timtylin]

Note that in almost all browsers, 1 in (and equivalently 2.54 cm) is simply shorthand for 96 pixels.

[jgm]

Here is what multimarkdown does:

[image]: http://path.to/image "Image title" width=400px height=400px
[link]:  http://path.to/link.html "Some Link" class=external
     style="border: solid black 1px;"

I like the basic idea. I'd like to allow something similar in inline images and links:

![image](http://path.to/image "Image title" width=4cm)
[link](http://path.to/link.html "some link" class=external)

Some questions and potential difficulties:

1. What units to allow? cm, em, and in will work for both LaTeX and HTML (using styles). px is more problematic.
2. There is some argument for reusing the existing attribute syntax (used now in headers and code blocks) for consistency. That would suggest something like

[image]: http://path.to/image "Image title" {width=400px height=400px}
[link]:  http://path.to/link.html "some link" {.external style="border: solid black 1 px;"}

and in inline form,

![image](http://path.to/image "title" {width=400px height=400px})

or should it be

![image](http://path.to/image "title"){width=400px height=400px}

3. Another advantage of the curly-bracket form is that it avoids some parsing difficulties, especially when no title is present. Currently spaces are allowed in the URL part of a markdown link, so

[link](http://path.to/link.html class=external)

would be parsed as a link to the URL http://path.to/link.html%20class=external, and the multimarkdown format would break this existing behavior. Requiring curly brackets for attributes gives the parser a clear signal.

[jgm]

Is this hard coded in the browsers, or is it sensitive to the system
DPI setting?

On linux, at least, you can change the system DPI:
https://wiki.archlinux.org/index.php/Xorg#Setting_DPI_manually

+++ Tim Lin [Oct 21 13 13:05 ]:

Note that in almost all browsers, 1 in (and equivalently 2.54 cm) is
simply shorthand for [1]96 pixels.

—
Reply to this email directly or [2]view it on GitHub.
[xJAuenYDiIoVt3LF3y6848lkNPgY-QGjRmh7vcZK4inXnxdKsKiEjkMtMuE82YEe.gif]

References

1. http://www.quirksmode.org/blog/archives/2012/11/the_css_physica.html
2. Syntax for specifying image size #261 (comment)

[mb21]

I'm all for

![image](http://path.to/image "title"){width=400px height=400px class=myClass}

So we have each type of bracket besides the others [...](...){...} instead of [...](...{...}...). Also we're free to add additional attributes.

[ambs]

👍 for [...](...){...}

[timtylin]

@jgm: As far as I can tell, this convention is part of the official CSS specification and does not obey variations in OS or device. I think there's currently no reliable method to have perfect physical sizing control short of probing for the actual physical device, and I'm not sure ultimately how useful it is anyways.

IMO one of the best practices is to use widths relative to the container. In LaTeX I've always used something like width=0.5\textwidth and in HTML that corresponds to width=50% (defaults to be relative to container width). I don't have any idea whether the other formats support this kind of thing, but it would make the most sense to me.

[ambs]

I kind of agree with @evitaerc. I do that always, too, for LaTeX. But although LaTeX has a fixed page width, that is not true for HTML. But we can always support both (relative or absolute).

[nichtich]

@mb21 and @ambs: So how would you expect to specify the size of an image for both, LaTeX/PDF and HTML/EPUB format? The original image will unlikely have 96 DPI. This would not work, would it?:

![image](http://path.to/image "title"){width=400px height=400px width=5cm height=5cm}

Its usual to create PDF and HTML from the same Markdown source. If the proposed syntax cannot support both of them at the same time, one must manually change the image file as it is needed now. A possible solution with limited usability is to support a "dpi" parameter. For instance 5cm / 203DPI = 400px:

![image](http://path.to/image "title"){width=400px height=400px dpi=203}
![image](http://path.to/image "title"){width=5cm height=5cm dpi=203}

[timtylin]

@ambs: HTML at least has the container width that you can almost always count on. Having a width relative to the container width is also ideologically closer to the current almost de-facto system of rendering on a column/grid system for CSS (think of percentages like laying out a picture across 100 columns).

On the other hand, absolute sizes like pixels will test your resolve to live when you want to make it work for high-DPI handheld devices and 4K desktop displays.

[dashed]

I like @nichtich's suggestion to have separate dimension specification for HTML and LaTeX (pdf output). You do not want to fixate pixel to an actual physical measurement. This is in my opinion the best way to go.

Other than the default case:

![image](path/to/image "title")

One may optionally include dimensions for either HTML or LaTeX:

1. ![image](/path/to/image "title"){width=400px height=400px}
2. ![image](path/to/image "title"){rwidth=5cm rheight=5cm}
3. ![image](path/to/image "title"){width=400px height=400px rwidth=5cm rheight=5cm}

rheight and rwidth may refer to 'real' height and width for physical outputs.

If either dimensions for HTMl and LaTeX are excluded, then they're assumed to be default and handled by the browser or LaTeX pdf compiler accordingly.

Other cases may include that, if you only include rheight or rwidth, the aspect ratio is kept. I think this is the default behaviour in LaTeX without having to specify keepaspectratio.

How do we separate attributes for either LaTeX and HTML?

For instance,
![image](path/to/image "title"){width=400px, height=400px, rwidth=5cm, rheight=5cm, style="border:5px solid red;", class="imagestyle", angle=180}

Does anyone know if LaTeX throws an error if you just dump the attributes into:
\includegraphics[dump_attributes_here]{path/to/image}

[jgm]

I don't see the need for the complexity of separate measures for
different formats, if specifications like "50%" or "5cm" will work
for both. We can just disallow px measurements, or discourage them.

[uvtc]

![...](...){...} would mesh nicely with:

• the fenced code block attribute syntax: ~~~{#my-code .haskell} ...
• header attribute syntax: ## Section {#some-id}
• the sometimes-proposed span syntax like [...]{...}
• the sometimes-proposed fenced div syntax, possibly like ^^^{#some-id .some-class}...

[uvtc]

Added my comment about the div syntax (mentioned in prev comment here) to the end of issue #168.

[dashed]

@jgm If that's the case, would you at least allow the style attribute for HTML? That way, style="height=40px;width=25px;" becomes an alternative for those who want to specify the height and width using px.

[mb21]

Personally, I usually want to use a width for TeX, and assign a class for HTML (so I can set width, floating and responsive design properties with CSS). I don't want to use percentages of the parent because scaling images in browsers by anything other than multiples of two usually produces aliasing artifacts.

[dashed]

👍 Slick. Thanks @jgm!

[legrostdg]

\o/

[signalwerk]

Awesome! Thx!

[ambs]

WEEEEEEEEE!!!

[katrinleinweber]

Merci! ☀️

[ivoanjo]

This is huge, thanks! 👍

[frumbert]

Cool, but this won't be available in a full release until 1.16, right? I can't create a windows version of this branch using either stack or cabal.

[jgm]

+++ TIm St.Clair [Nov 22 15 17:41 ]:

Cool, but this won't be available in a full release until 1.16, right?
I can't create a windows version of this branch using either stack or
cabal.

What happens on Windows when you try with stack?

[frumbert]

Windows 2003 R2 Sp2 32-Bit, on VirtualBox; git, node, cygwin, miktex, haskell platform, cabal, etc all installed and updated ok. (ghc version 7.8.3)

$ stack install
Downloading lts-3.13 build plan ...FailedConnectionException2 "raw.githubusercon
tent.com" 443 True user error (cryptonite: random: cannot get any source of entr
opy on this system)

, and, when compiling via cabal, I also get cryptonite can't be installed (cryptonite: random: cannot get any source of entropy on this system).

[jgm]

https://hackage.haskell.org/package/cryptonite
says it supports Windows >= 8.

Is Windows 2003 < Windows 8? If so, that's your problem.

+++ TIm St.Clair [Nov 22 15 21:19 ]:

Windows 2003 R2 Sp2 32-Bit, on VirtualBox; git, node, cygwin, miktex,
haskell platform, cabal, etc all installed and updated ok. (ghc version
7.8.3)

$ stack install
Downloading lts-3.13 build plan ...FailedConnectionException2
"raw.githubusercon
tent.com" 443 True user error (cryptonite: random: cannot get any
source of entr
opy on this system)

when compiling via cabal, I also get cryptonite can't be installed
(cryptonite: random: cannot get any source of entropy on this system).

—
Reply to this email directly or [1]view it on GitHub.

References

1. Syntax for specifying image size #261 (comment)

[frumbert]

slaps forehead
compiling happily on my win10 box...

i really have to trash that old thing and stop using it.

[Wind4Greg]

I really want this feature but can't get Pandoc to build with stack on Windows 10. Followed the instructions from https:/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc, downloaded the latest stack from http://docs.haskellstack.org/en/stable/install_and_upgrade.html#windows. But I get a weird error seemingly unrelated to Pandoc:

    C:\Users\Greg\AppData\Local\Temp\stack5940\HTTP-4000.2.21\Network\HTTP\Proxy.hs:85:22:
        Not in scope: ‘liftM’
        Perhaps you meant ‘liftM2’ (imported from Control.Monad)

Which has something to do with a Haskell HTTP library. Is there any other way to get this feature? Or is there something about Haskell on windows that I'm overlooking.

[jgm]

Someone has reported the same issue on pandoc-discuss.
I haven't had a chance to build yet on a Windows machine or
investigate further.

+++ Greg Bernstein [Dec 08 15 11:31 ]:

I really want this feature but can't get Pandoc to build with stack on
Windows 10. Followed the instructions from
[1]https:/jgm/pandoc/wiki/Installing-the-development-versio
n-of-pandoc, downloaded the latest stack from
[2]http://docs.haskellstack.org/en/stable/install_and_upgrade.html#wind
ows. But I get a weird error seemingly unrelated to Pandoc:
C:\Users\Greg\AppData\Local\Temp\stack5940\HTTP-4000.2.21\Network\HTTP\Proxy
.hs:85:22:
Not in scope: ‘liftM’
Perhaps you meant ‘liftM2’ (imported from Control.Monad)

Which has something to do with a Haskell HTTP library. Is there any
other way to get this feature? Or is there something about Haskell on
windows that I'm overlooking.

—
Reply to this email directly or [3]view it on GitHub.

References

1. https:/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc
2. http://docs.haskellstack.org/en/stable/install_and_upgrade.html#windows
3. Syntax for specifying image size #261 (comment)

[Wind4Greg]

Thanks. It's a windows/Haskell issue, using a VM was able to build it on Ubuntu and see first hand this really nice feature. I'll watch pandoc-discuss for the windows fix.
Cheers.

[yan-zaretskiy]

Is there an estimate of when this feature will reach the release?

[mb21]

Image dimensions have been in 1.16 for a while already...

[yan-zaretskiy]

Oops, my bad!

[mofosyne]

How do you use it btw? I can't seem to find instructions on using it in the manual.

[KurtPfeifle]

@mofosyne:

Search for link_attributes.

See here: http://pandoc.org/README.html#images

[flrgsr]

It seems this only works with the width and height keyword.
What about scale?

I would love to be able to do something like this:

![image description](images/myimage.png){ scale=0.5 }

Am I missing something or is this really impossible yet?

edit: I care about the latex backend

So as desired output I would like to have:
\begin{figure} \centering \includegraphics[scale=0.5]{images/myimage.png} \caption{the caption goes here} \end{figure}

[ghost]

Similarly to @flrgsr I would like to be able to scale images, mainly so that I don't need to make all my images super low-res and/or hardcode the image sizes in the markdown just to accommodate the scaling with HTML (which is super low DPI per default).

[mb21]

It sounds what you guys are really looking for is:

![](image.jpg){srcset="image_2x.jpg 2x"}

[ghost]

Yes! Is there a nicer way to write that? Also, does that work with all backends (e.g. both PDF and HTML)?

Edit: also if this actually scales up/down the pixels before inserting the image that doesn't help, since then it will reduce the resolution. I can do that myself in GIMP - the point is scaling down the size without reducing the image resolution to support high DPI output properly

[mb21]

Depending on your taste, it's already quite nice.. (at least it's consistent with other syntax) see http://pandoc.org/MANUAL.html#extension-link_attributes for the rationale.

No, if you generate your PDF with LaTeX (which is the default), it will use image.jpg. You can always write a filter that scales your images, or write some CSS to your needs...

[ghost]

So what about HTML? HTML is one of my required main targets so if it's not working nicely there, sadly I can't really use it.

Filters are often mentioned here, but I consider them quite uninteresting since they require something outside markdown. Similar to CSS, except CSS is even a lot worse since it requires specific stuff for one output format only. Write once in a universal format, output to all targets shouldn't require this..

[mb21]

So what about HTML?

What about it? Tell us what HTML you expect pandoc to generate for what input...

Filters are often mentioned here, but I consider them quite uninteresting since they require something outside markdown.

That's not correct. Filters are for you to customize pandoc's behaviour, see https://pandoc.org/scripting.html

But this discussion/QA should move to pandoc-discuss. This issue is closed and we're spamming the people subscribed to it.