Add the ability to optionally include images in a gallery that were saved to disk #208
Conversation
|
I haven't tested this but I think this will be a problem with the notebook-style examples where you have multiple cells and not all figures are saved in the same cell. I believe some figures will be repeated in the HTML. Also the order of saved figures will not be related with the order of the example execution which may be confusing if you have multiple figures. Rather than trying to treat similarly saved png and matplotlib figures, maybe we could have an additional "Saved Files" section, which shows saved files by name. This way it is more clear where the image comes from in the rendered HTML. I am thinking aloud here and I don't have a good solution for what you want to do right now. |
Actually I just quickly tested it and this looks fine, I am guessing because you are moving images out of the way as soon as you discover them.
I found an example of this in your gallery actually: I think we should sort the result of
I thought a bit more about this and I stick to my proposal. So basically on top of the two things we already have as the output of a cell, i.e. interactive figures and standard output, we would have "saved images". It would be good to display the filename reasonably prominently to make it easier to track which image is which file and understand where it comes from in the example. By the way this feature could be a way of supporting matplotlib animations #150 by saving to a .gif in the example. @Titan-C @GaelVaroquaux any opinions? |
|
I am quite uncomfortable with that, because it is moving us further away
from the notebook model. We are already not really notebooks, and things
behave a bit different in the notebook and in the Python examples. This
will increase the gap. I don't like it.
|
Yeah I thought the same too actually. It should be possible to add some kind of formatting in the rendered HTML to make it clear that those are saved image files. Differentiating between interactive figures and saved images is actually the point of adding another section in the output. |
|
Still, it's pulling the project away from notebooks, while everybody else
is going onto notebooks.
I haven't fully understood the compeling reason for saving to disk.
|
The main point is that it makes sphinx-gallery usable by packages that saves images to disk (as seems to be the case of yt) and do not have figures e.g. One thing to keep in mind also is that the changes needed to make it work are fairly small. It is not a conclusive argument by itself but still certainly something to take into account. |
|
The main point is that it makes sphinx-gallery usable by packages that saves
images to disk (as seems to be the case of yt) and do not have figures e.g.
matplotlib.pyplot does.
yt doesn't use matplotlib? I thought that it did (sorry, I am behind the
great firewall of China, and google doesn't work, and I am not very good
with baidu :$).
For non matplotlib-based plotting, the vision was to have backends that
register with sphinx-gallery in the conf.py. I thought that we had done
that with Mayavi, but looking at the codebase, we haven't.
I would much prefer that solution: it avoids modifying sphinx-gallery
each time a new situation comes. We could have a callback that is called
after the execution of each cell, with the locals and globals passed in
and a few other meta-data (such as the file name executed), and it would
return the restructured code to be included.
|
|
yt does use matplotlib but not pyplot. There is no global list of figures created by a yt plotting session (since we're not using pyplot) so the approach used by sphinx-gallery for mayavi and pyplot simply won't work, there's no way to figure after a script has run which figures it produced except by inspecting a folder for images saved to disk. If I were using a plugin here the plugin would just be looking for images saved to disk. What if I were trying to document a library like Pillow which saves images to disk completely independent of matplotlib and also does not have a global registry of figures? I'd need something exactly like what's in this pull request. This is a sufficiently general desire that I think it would be very helpful to include in the library itself. |
|
Based on @choldgraf 's feedback in #206, I think that we should implement this functionality. A bit more work is needed on this PR, mainly:
|
|
I though I replied to this, but since I'm out on a school with other
things in mind I just have not. I actually like the idea of capturing
other output objects, which we now limit to stdout, matplotlib & mayavi
plots.
In such scheme I agree with @lesteve to give this new output its own
output block, not mix it as if they were the standard matplotlib pop-up
plots.
What I don't like of this implementation is that the image capturing is
just to generic: just a glob to `*.png`. This could give unwanted
behavior. I image for example in the scikit-image project they certainly
load `png` or `jpg` images for further processing. Letting this glob
just capture everything in the local folder and move it to the gallery
images output would just break their gallery, they would run out of
their locally available images. Yes this feature is disabled by default,
but I just fear the generality of the procedure to break things. Second
concern for the future as Multiprocessor support is becoming a requested
feature PR #25. Race conditions will become a real issue on this
implementation. 2 parallel threads will glob the same files on disk, then
rendered htmls will have mixed images and then one thread will move the file
first making the other thread raise a FilenotfoundError.
On top of @GaelVaroquaux suggestions. The conf.py option shall be
`capture_yt_save_figures`, it needs to be indeed a regex. But ignorant
of the yt code, is it possible to include an internal variable that
names written files such that it is specific they are output files and
from which python script they are generated? see concerns above.
In the case we want to make this very general an capture other arbitrary
objects other than png, like gif animations issue #150. Then I would go
for making a per file sphinx-gallery comment that signal how to capture
a specific file. And then force the user to use the rst comments to load
the captured file, see my comments on issue #199, weather is an image,
video, html, text file for download, numpy data file, etc. and how we
want to display it? as downloadable file? an rendered image.
|
|
I don't have any comments about implementation, but I just want to chime in and add that this would be a very helpful feature for pycortex. A lot of our plotting is actually done using webGL in a browser, and we really want to make a pretty gallery to show off the pretty outputs. Being able to insert screenshots as thumbnails would be a great help! |
Are the screenshots generated by the example or are they done manually ? |
|
I'm hoping to do the screenshots manually so they could include the GUI. Currently it's possible to automatically screenshot just the webGL canvas (with no GUI). One workaround that I hadn't considered before would be to load the automatic screenshot and then display it using matplotlib in order to generate a thumbnail for the gallery. That would be possible, but ugly (and would end up with an example showing the user how to do something stupid that they would never want to do). |
This is what I thought. Your use case is slightly different than the yt case then. One of the point of sphinx-gallery is to make sure that the script and its outputs are in sync by running the example. I think the goal of this PR is to allow capturing saved images generated by the example. Note that notebook-style cells allow you to write any rst as comments so you can include images if you have a screenshot somewhere. It's just that they will not be used for the thumbnail in the gallery. |
|
attn @choldgraf |
|
what's the status of this PR? it sounds like there's still debate as to whether to implement this feature in the first place... @ngoldbaum or @lesteve any thoughts on this? I think we should decide and get this PR either merged or closed :-) |
|
I don't have any time to spend on this. If it's causing noise to have this open, please close it. |
This resolves #206. I'll add documentation and a test for this feature and the new configuration option if this approach is copacetic.
This change makes it so that we can include images in a gallery for code that does not save image via pyplot or mayavi. It's enabled via a new configuration option
find_saved_figures, which defaults toFalse.If it's
True, we inspect the directory containing the example script (i.e. the directory where the script was being run) for png images. If we find any, we move them to the output directory for the gallery and give them names following the template used for pyplot figures.I've had to modify the API of the internal
save_figuresfunction slightly. As far as I can tell this function only has consumers inside ofsphinx-galleryso it should be ok to change the API, but please let me know if that's incorrect.There are a couple things that could be improved: