Super figure is a vscode extension that implements integration for Inkscape, Gimp and other image editors as means to quickly launch and edit figures and see the results is your Latex, Typst and Markdown files.
This extension is inspired by the work of Gilles Castel and his Vim plugin. May his blog not had a good SEO, i wouldn't have found it and had this idea, unfortunately he passed away in July 2022, so i'm dedicating this work to him as a thanks and to show that even in our passing, our work will continue to inspire others and move knowledge and human kind forwards, because we stand on the shoulder's of giants, rest in peace Gilles.
Install on:
This extension enables you to launch image files from Latex, Typst or Markdown directly into a external image editor, like Inkscape or Gimp, for that just select the text of the image filename, open the command palette with ctrl+shift+p, then search for super figure, a list of commands will be shown.
Some key features:
- Edit file externally with a simple command just by selecting the filepath!
- Files will be created based on a template if they not exist yet
- Ready to go snippets for Latex, Typst and Markdown via commands
- onSave commands for when extra work is needed after editing the file. Ex: Saving
svgfiles topdfandtexfor latex. - Image file renaming
- Keybindings
Sample using Latex and Inkscape:
Sample using Markdown and Gimp:
- super-figure
- Features
- TOC
- Usage
- FAQ
- Commands
- Edit Figure (
super-figure.editFigure) - Rename figure (
super-figure.renameFigure) - Edit Figure based on the file extension (
super-figure.editFigureExtension) - Edit Vector figure (
super-figure.editVector) - Edit Bitmap figure (
super-figure.editBitmap) - Insert vector figure as latex snippet (
super-figure.insertLatexVectorFigure) - Insert bitmap figure as latex snippet (
super-figure.insertLatexBitmapFigure) - Insert Latex Preamble (
super-figure.insertLatexPre) - Insert vector figure as markdown snippet (
super-figure.insertMarkdownVectorFigure) - Insert bitmap figure as markdown snippet (
super-figure.insertMarkdownBitmapFigure) - Insert vector figure as typst snippet (
super-figure.insertTypstVectorFigure) - Insert bitmap figure as typst snippet (
super-figure.insertTypstBitmapFigure)
- Edit Figure (
- Requirements
- Extension Settings
- Known Issues
- Planned Features
- Release Notes
Super figure should fully work out the box if you have Inkscape and Gimp installed on Windows or Linux!
For common problems go to the FAQ.
For detailed configuration info, go to Configuration.
For a quick setup config if your don't work, try this. After installing the extension, press ctrl+shift+p, then type/search for Preferences: Open Settings (UI), look on the left for the Extensions dropdown, then scroll until you find Super Figure, click it, then you need to alter:
Bitmap Figure Editor: The full path to your bitmap edit tool, like Gimp or PhotoshopVector Figure Editor: The full path to your vector edit tool, like Inkscape or Corel
In case of more complicated and mysterious problems, just create a new issue report here.
Two default keybindings are defined, for vector and bitmap editing, both work in latex and markdown and execute the corresponding command to the language.
ctrl+alt+v: Insert Vector figurectrl+alt+b: Insert Bitmap figurectrl+alt+r: Rename figure
Every configuration is set by default, but it may not work out of the box for you, for that i recommend that you set first:
The executables full path and their arguments to launch the figures correctly:
super-figure.vectorFigureEditorsuper-figure.vectorFigureEditorArgssuper-figure.bitmapFigureEditorsuper-figure.bitmapFigureEditorArgs
See also Variables for more info.
After this i also recommend you to configure the onSave commands, because every figure created/modified by the extension is watched and emits an event everytime you save the figure in the external editor, this can be used to trigger conversion events. See On Save commands.
After installed the extension provides the folder super-figure/templates, under the home folder, this folder contains templates for svg, xcf and png files, that will be suggested to you when creating new files, so if you need more templates, just add them to this folder and change the preferred ones in the config file. See super-figure.vectorTemplate and super-figure.bitmapTemplate under Configurations List.
Folder location:
-
Windows
C:Users\your_user\.config\super-templates\templates\
-
Linux
~\.config\super-templates\templates\
For Inkscape, using the vector edit commands, svg files will be created, but latex doesn't use svg files, latex uses pdf files converted every time the svg is saved.
A nice feature here is that any text box you include in Inkscape, and has a tex math sequence, $math$ or \[math\], will be rendered by latex as typeset math text, not embedded in the image, but as a overlay os native text over the image.
"super-figure.onVectorFileSave": "\"${executable}\" \"${file}\" --export-area-page --export-dpi 300 --export-type=pdf --export-latex --export-filename \"${dir}/${basename}.pdf\""For better visualization:
`
"${executable}" "${file}"
--export-area-page
--export-dpi 300
--export-type=pdf
--export-latex
--export-filename "${dir}/${basename}.pdf"
`Here, everytime Inkscape saves the file, the extension listens to the event and executes the provided command, that also uses Inkscape, to generate a latex friendly pdf. This way, after the onSave command was executed, two files are generated:
images/figure.svgimages/figure.pdfimages/figure.pdf_tex
Credits: Gilles Castel
Gimp also does takes advantage of this, by using the batch preprocessor, the friendly editable .xcf files are exported to png ones, for insertion into latex and markdown.
"super-figure.onBitmapFileSave": "\"${executable}\" -n -i -b '(let* ( (filename \"${file}\") (fileout \"${dir}/${basename}.png\") (image 0) (layer 0) ) (set! image (car (gimp-file-load RUN-NONINTERACTIVE filename filename))) (set! layer (car (gimp-image-merge-visible-layers image CLIP-TO-IMAGE))) (gimp-file-save RUN-NONINTERACTIVE image layer fileout fileout) (gimp-image-delete image) (gimp-quit 0))'"For better visualization:
(let*
(
(filename "${file}")
(fileout "${dir}/${basename}.png")
(image 0)
(layer 0)
)
(set! image (car (gimp-file-load RUN-NONINTERACTIVE filename filename)))
(set! layer (car (gimp-image-merge-visible-layers image CLIP-TO-IMAGE)))
(gimp-file-save RUN-NONINTERACTIVE image layer fileout fileout)
(gimp-image-delete image)
(gimp-quit 0)
)Here, everytime Gimp saves the file, the extension listens to the event and executes the provided command, that uses the batch script to generate a png figure, so after the onSave command was executed, the directory will look like this:
images/figure.xcfimages/figure.png
Credits: Laurence Gonsalves
Launches a quick item selector on which you will be able to choose how you edit the file, all options are alias to the commands:
Renames a figure, and for that, just select your image name, like images/figure1 in this examples:
\begin{figure}[ht]
\centering
\caption{}
%\incsvg{path/}{path/file}
\incsvg{images}{images/figure1}\\
\label{fig:sample}
\end{figure}Then press the shortcut ctrl+alt+r or open up the command palette and go for the command Rename.
You might be prompted to select the exact file, since the extension cannot guess the extension if multiple file with the same name and different extension might exist.
After that input the new file name and boom, the text will be updated, the file will be renamed, if applicable the onSave command will be executed accordingly, regenerating files, and finally the file will be put in the watch list, in which the onSave command will be executed might the file be modified externally.
After selecting the filename with the file extension, the type of the file will be determined, as vector or bitmap, then the file will be opened in the correct external editor.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.vectorTemplate configuration and will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.bitmapTemplate configuration and will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.vectorTemplate configuration, a snippet will be inserted, and the file will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
Selection example:
images/myVectorImageGenerated snippet:
\begin{figure}[ht]
\centering
\caption{}
%\incsvg{path/}{path/file}
\incsvg{images}{images/myVectorImage}\\
\label{fig:myVectorImage}
\end{figure}Note: The latex macro \incsvg is special to this extension, the declaration for this macro and the latex preamble can be inserted as a snippet in the document by executing the vscode command, via command palette, Insert Latex Preamble.
After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.bitmapTemplate configuration, a snippet will be inserted, and the file will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
Selection example:
images/myBitmapImageGenerated snippet:
\begin{figure}[ht]
\centering
\caption{}
\includegraphics[width=16cm]{images/myBitmapImage.png}\\
\label{fig:myBitmapImage}
\end{figure}Note: The latex macro \incsvg is special to this extension, the declaration for this macro and the latex preamble can be inserted as a snippet in the document by executing the vscode command, via command palette, Insert Latex Preamble.
The latex preamble defines the use of the package import, necessary due to file path correction for files that includes other files, and the vector image include command.
Generate preamble:
\usepackage{import}
\newcommand{\incsvg}[2]{%
\def\svgwidth{\columnwidth}
\graphicspath{{#1}}
\input{#2.pdf_tex}
}After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.vectorTemplate configuration, a snippet will be inserted, and the file will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
Selection example:
images/myVectorImageGenerated snippet:
After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.bitmapTemplate configuration, a snippet will be inserted, and the file will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
Selection example:
images/myBitmapImageGenerated snippet:
After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.vectorTemplate configuration, a snippet will be inserted, and the file will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
Selection example:
images/myVectorImageGenerated snippet:
#image("images/myVectorImage.svg")After selecting the filename in the editor, without the file extension, the file type will be assumed as the same as the template set in the super-figure.bitmapTemplate configuration, a snippet will be inserted, and the file will be opened.
If the file doesn't exist, you will be prompted to use a suggested file template, after confirmation, the file will be opened normally.
Selection example:
images/myBitmapImageGenerated snippet:
#image("images/myBitmapImage.png")This extension was made to be customizable, but the real goal here is to make markdown and latex notes/papers easier to write, in the figure department at least. So, to use some out of the box features i recommend you install these programs and packages:
- Latex
texlive-bintexlive-bibtexextra (texlive-most)texlive-core (texlive-most)texlive-fontsextra (texlive-most)texlive-formatsextra (texlive-most)texlive-games (texlive-most)texlive-humanities (texlive-most)texlive-latexextra (texlive-most)texlive-music (texlive-most)texlive-pictures (texlive-most)texlive-pstricks (texlive-most)texlive-science (texlive-most)
Install command:
$ sudo pacman -S texlive-bin texlive-most- Editors
InkscapeGimp
Install command:
$ sudo pacman -S gimp inkscapeThe Args configurations and onSave commands, offer variables support, you can see that the default for the Args is ${file}, so the executable can open the file as argument. More variables are available:
${file}: the filename of the figure (with file extension). Ex:images/figure.svg${basename}: The basename without the file extension. Ex:figure${dir}: The parent directory. Ex:images${executable}: The current set executable depending on the type of figure, either vector or bitmap. Ex:images
super-figure.vectorFigureEditor:
"type": "string",
"default": "/usr/bin/inkscape",
"description": "Full path for a vector figure editor executable. Ex: /usr/bin/inkscape"super-figure.vectorFigureEditorArgs:
"type": "string",
"default": "${file}",
"description": "Commands line argumments to be passed to the vector editing executable. Ex: ${file} --option=5"super-figure.vectorFileExt:
"type": "string",
"default": "eps,svgz,pdf,ps,ai,odg",
"description": "List of file extensions to check for vector images"super-figure.vectorTemplate:
"type": "string",
"default": "~/.config/super-figure/templates/template.svg",
"description": "Preferred file template for creating a vector figure that doesn't exist yet. Will try to use a template of the same file extension first, then this"super-figure.onVectorFileSave:
"type": "string",
"default": "${executable} ${file} --export-area-page --export-dpi 300 --export-type=pdf --export-latex --export-filename ${dir}/${basename}.pdf",
"description": "Callback command to when the vector figure is saved to disk. Ex: '/usr/bin/inkscape' --export-filename ${basename}.pdf"super-figure.bitmapFigureEditor:
"type": "string",
"default": "/usr/bin/gimp",
"description": "Full path for a bitmap figure editor executable. Ex: /usr/bin/gimp"super-figure.bitmapFigureEditorArgs:
"type": "string",
"default": "${file}",
"description": "Commands line argumments to be passed to the bitmap editing executable. Ex: ${file} --option=5"super-figure.bitmapFileExt:
"type": "string",
"default": "png,jpeg,jpg,gif,tiff,bmp,xcf",
"description": "List of file extensions to check for bitmap images"super-figure.bitmapTemplate:
"type": "string",
"default": "~/.config/super-figure/templates/template.xcf",
"description": "Preferred file template for creating a bitmap figure that doesn't exist yet. Will try to use a template of the same file extension first, then this"super-figure.onBitmapFileSave
"type": "string",
"default": "${executable} -n -i -b '(let* ( (filename \"${file}\") (fileout \"${dir}/$:{basename}.png\") (image 0) (layer 0) ) (set! image (car (gimp-file-load RUN-NONINTERACTIVE filename filename))) (set! layer (car (gimp-image-merge-visible-layers image CLIP-TO-IMAGE))) (gimp-file-save RUN-NONINTERACTIVE image layer fileout fileout) (gimp-image-delete image) (gimp-quit 0))'",
"description": "Callback command to when the bitmap figure is saved to disk. Ex: '/usr/bin/inkscape' --export-filename ${basename}.pdf"super-figure.filesToWatch:
"type": "array",
"default": [],
"description": "Array that stores files to be watched. on*FileSave commands will be called for these."- No bugs, yet...
-
Configuration for an array of optional programs do launch figure with, along with a dropdown menu for selecting those
-
Hability to paste and drop files directly into vscode and generate the snippets accordingly, similar to the extension Paste Image.
Small refactor and improvements.
Added Typst support!
Bug fixes for onSave actions on windows
Bug fixes and a rename feature
Bug fixes for Windows (path resolving related)
Initial release!