Linking to figures in Sphinx - python-sphinx

I have some images in my documentation created as a set of reST files in Sphinx. I prefer to keep them pretty small, and I want the user to click on them to get the larger image. The smaller image is not for file size reasons but for presentation reasons. I do not find a syntactic way to combine the tags image: or figure: with ref: or link:.
.. image:: _static/my_image_small.png
and I have a bigger version in the same folder: my_image_large.png.
If you come up with a solution, should the larger image just be a file with an explicit link to it or do I create a reST file with an additional image: tag? An alternative could be to play with the image sizes in the reST file, but then I still do not know how to create the link from the small image to the large image. Is there a way to bypass the Sphinx generator and just give the HTML that I want?

There are two ways you can do it.
The first is to just insert a bit of "raw" HTML:
.. raw:: html
<a href=....><img src=....
The second is to make the image clickable. That way you can link it to a bigger image:
.. image:: _static/my_image_small.png
:target: _static/my_image_large.png
There are more options you can give, btw. See the full list in the restructured text documentation.

Related

Why are images in pdf sometimes sliced into multiple images?

Noticed that images sometimes are sliced up in PDFs.
Steps:
insert an image with a high resoultion (3000x1800) into a .docx
use "Microsoft Print to PDF" option of Word to convert to PDF
extracting all images with pdfimages or pymupdf
Result:
Image is sliced horizontally into three images
Questions:
What exactly happens in the in the transition from .docx to pdf (or in generell in the process to pdf) that makes the converter slice it up into three images instead of one?
Do the individuell XObjects of the sliced images contain information which says that these three images belong to originally one?
How do I know how the images are sliced (horizontally / vertically) and what if originally there were two images inserted into the .docx file and both of them are sliced. Can you tell if slice x belongs to original image y or z?
So, as you have found out: because the code which generates the PDF choose to do so.
The technical reasons may be various - it could be that historically there were printers which would only have so much memory, and would need to get limiterd size-images when printing, and someone at some point when writing the PDF export code present in Microsoft Office choose to apply this limit.
Anyway, technically, as put in the comments, an image in a PDF file could be composed of unlimited smaller images collated together.
Now, the second part, and your actual question: to know whether images ibn a PDF file belong together in a single original image one would need a custom extractor tool to check the geometry of all images in the document and find out which images have no margins or boundaries with others - it would not be that hard to do for well behaved files (which we can't know if MS Office generated files are: there are ways to obfuscate image positioning by making it indirectly). The metadata in the image-parts may or may not contain information that would allow one to recompose the original image: it would be up to the code generating the PDF to include this metadata or not - but the geometry can't lie in this case: if the final document presents a single image visually, it is possible to detect that when fetching the images.

AsciiDoc: How can I place graphical hints on an image

I am using AsciiDoc with Asciidoctor Gradle Plugin to generate technical documentation as PDF.
When I used M$ Word, I could easily place forms on an image, for example
colored rectangles,
boxes with numbers or
even links to sections within the document,
to better point out interesting areas within the image.
Example:
On the example image I have placed two rectangles and each one contains a link (starting with the word «Dialogbereich») leading to a other sections within the document.
Is it possible to achieve something like this (directly) in AsciiDoc?
Note that the answers to asciidoc: how to add callouts asciidoc to image do not apply here as the Asciidoctor PDF backend does not use DocBook to generate the PDF.
I know I could create a layered image in GIMP to at least place the rectangles. However, that wouldn't help me with the links.

How to set size for local image using knitr for markdown?

I have a local image that I would like to include in an .Rmd file which I will then knit and convert to HTML slides with Pandoc. Per this post, this will insert the local image :
![Image Title](path/to/your/image)
Is there a way to modify this code to also set the image size?
The question is old, but still receives a lot of attention. As the existing answers are outdated, here a more up-to-date solution:
Resizing local images
As of knitr 1.12, there is the function include_graphics. From ?include_graphics (emphasis mine):
The major advantage of using this function is that it is portable in the sense that it works for all document formats that knitr supports, so you do not need to think if you have to use, for example, LaTeX or Markdown syntax, to embed an external image. Chunk options related to graphics output that work for normal R plots also work for these images, such as out.width and out.height.
Example:
```{r, out.width = "400px"}
knitr::include_graphics("path/to/image.png")
```
Advantages:
Over agastudy's answer: No need for external libraries or for re-rastering the image.
Over Shruti Kapoor's answer: No need to manually write HTML. Besides, the image is included in the self-contained version of the file.
Including generated images
To compose the path to a plot that is generated in a chunk (but not included), the chunk options opts_current$get("fig.path") (path to figure directory) as well as opts_current$get("label") (label of current chunk) may be useful. The following example uses fig.path to include the second of two images which were generated (but not displayed) in the first chunk:
```{r generate_figures, fig.show = "hide"}
library(knitr)
plot(1:10, col = "green")
plot(1:10, col = "red")
```
```{r}
include_graphics(sprintf("%sgenerate_figures-2.png", opts_current$get("fig.path")))
```
The general pattern of figure paths is [fig.path]/[chunklabel]-[i].[ext], where chunklabel is the label of the chunk where the plot has been generated, i is the plot index (within this chunk) and ext is the file extension (by default png in RMarkdown documents).
Un updated answer: in knitr 1.17 you can simply use
![Image Title](path/to/your/image){width=250px}
edit as per comment from #jsb
Note this works only without spaces, e.g. {width=250px} not {width = 250px}
You can also read the image using png package for example and plot it like a regular plot using grid.raster from the grid package.
```{r fig.width=1, fig.height=10,echo=FALSE}
library(png)
library(grid)
img <- readPNG("path/to/your/image")
grid.raster(img)
```
With this method you have full control of the size of you image.
Here's some options that keep the file self-contained without retastering the image:
Wrap the image in div tags
<div style="width:300px; height:200px">
![Image](path/to/image)
</div>
Use a stylesheet
test.Rmd
---
title: test
output: html_document
css: test.css
---
## Page with an image {#myImagePage}
![Image](path/to/image)
test.css
#myImagePage img {
width: 400px;
height: 200px;
}
If you have more than one image you might need to use the nth-child pseudo-selector for this second option.
If you are converting to HTML, you can set the size of the image using HTML syntax using:
<img src="path/to/image" height="400px" width="300px" />
or whatever height and width you would want to give.
Had the same issue today and found another option with knitr 1.16 when knitting to PDF (which requires that you have pandoc installed):
![Image Title](path/to/your/image){width=70%}
This method may require that you do a bit of trial and error to find the size that works for you. It is especially convenient because it makes putting two images side by side a prettier process. For example:
![Image 1](path/to/image1){width=70%}![Image 2](path/to/image2){width=30%}
You can get creative and stack a couple of these side by side and size them as you see fit. See https://rpubs.com/RatherBit/90926 for more ideas and examples.
Another option that worked for me is playing with the dpi option of knitr::include_graphics() like this:
```{r}
knitr::include_graphics("path/to/image.png", dpi = 100)
```
... which sure (unless you do the math) is trial and error compared to defining dimensions in the chunk, but maybe it will help somebody.
The knitr::include_graphics solution worked well for resizing the figures, but I was unable to figure out how to use it to produce side-by-side resized figures. I found this post useful for doing so.

Sphinx adding a link to an image or a figure

I am trying something rather basic in Sphinx. I have some images, but I prefer to keep them pretty small, and I want to allow the user to click on them to get the larger image.
I do not find a syntactic way to combine image: or figure: with ref: or link:.
.. image:: _static/my_image_small.png
and I have in the same folder my_image_large.png.
If you come up with a solution, should the larger image just be a file with an explicit link to it or do I create a reSt file with an additional image: tag?
An alternative could be to play with the image sizes in the reSt file, but then I still do not know how to create the link from the small image to the large image.
Thank you for helping me.
Just use the target directive. You would end up with something like:
.. image:: _static/my_image_small.png
:target: _static/my_image_large.png
It is not strictly necessary to use the references to the static folder in your source. They will be copied to the _images folder anyway when you build the docs (so you will have them twice in your builds, without needing them there).
I always use a folder called figures next to the source folder where I manage the images. The my_image_large.png files, however, you would want to place in the _static folder as the contents will be copied on build.

Thumbnail-like behavior using target attribute of image directive

I use Sphinx to generate some docs. I have a reStructuredText document and I'd like to put an image into it. The case is that the image should be clickable so that after a user clicks the image then they should be shown this image in full size. I use the image directive and its target option like this:
.. image:: /images/some_image.png
:alt: Image descripion
:align: center
:target: `big_some_image`_
.. _big_some_image: /images/some_image.png
The problem is that in the rendered page I get:
<img src="../../../_images/some_image.png">
So there is correct src from the image directive but an incorrect href attribute from the hyperlink.
Questions:
is there any way to generate links in the way that image directive does it? I mean relative to the document.
is there any other (built in) way to have "thumbnail-> click -> big image" behaviour?
Simply use the scale option:
.. image:: large_image.png
:scale: 20%
When the scaled image is clicked on, the full image loads in its own window. So this doesn't increase the image size on the page, but that would be messy anyway.
When you use the image directive from within Sphinx, Sphinx does some special handling to find the image file and copy it into your project (like your _images directory), and then renders the HTML to point to that place.
But the target option just takes a URL as a parameter. It knows nothing about your Sphinx project, or how your images are laid out, and does not attempt to guess.
If you want to have it point to a larger version of the same file, you will likely need to do some manual steps (like maybe copying the file to a specific location), or maybe provide a relative URL to the large file, rather than the absolute URL you have in your example.
If you want to go a completely different way, you could also try overriding and modifying the HTML templates for your project to add some JavaScript to get the click-to-larger-image effect you want.
Looks like there is a Sphinx extension that does this now, and quite nicely at that, sphinxcontrib-fancybox 0.3.2. Install with pip, add it to your extensions in conf.py, and use the fancybox directive:
.. fancybox:: images/image.png
Relative links seem to work. For the Mapserver docs setup, if an image is placed in the images directory, a relative link like in the following code works in my local build. Here is an example using figure (the underscore ("_") before "images" in the target link is necessary):
.. figure:: ../../images/carto-elements.png
:height: 400
:width: 600
:align: center
:target: ../../_images/symcon-overlay.png

Resources