Welcome to scifig’s documentation!¶
Author: | François Boulogne |
---|---|
Devel: | github.com project |
Mirror: | git.sciunto.org |
Bugs: | github.com |
Generated: | Sep 27, 2017 |
License: | GPLv3 |
Contents:
What is it?¶
Introduction¶
Making figures for presentations, websites or publications usually take a lot of time. However, the process is usually the same (compile, convert and export). Thus, automation must be used to focus on the content and not on managing files. Based on this observation, I conceived a workflow and I wrote a software that automate this task.
The source code is available here: https://github.com/sciunto-org/scifig
Choices¶
Languages and softwares for figures¶
We need to choose a technology to make figures. I like to write code, I’m efficient that way, so I choose LaTeX because I already use it for my documents and my presentations. To draw figures, pstricks or Tikz can be used. I tried both and Tikz looked to me more efficient (for loops for instance). To make plots, I’m familiar with gnuplot for almost a decade now. Gnuplot has a tikz terminal and this is lucky. It will be very easy to combine drawings and plots. For rare other needs (chemical formulae), LaTeX usually have what we need.
Ktikz and gummi are really helpful to prepare drawings. They refresh the output while you edit the code. It’s almost a live mode.
Output formats¶
- tex (standalone file)
- eps
- svg
Workflow¶
Now, we need to find a strategy to make our figures.
Drawings
- tikz file: the code you write with Ktiz for instance, between \begin and \end{tikzpicture}
- tex file: we decorate the tikz file with some packages and a document class (standalone) to have a croped image
- pdf file: the tex file compiled with pdflatex
- eps file: pdf to eps
- svg file: pdf to svg
Plots with gnuplot
- plt file: this is the standard gnuplot script to make a figure, with tikz terminal
- tikz file: code generated by gnuplot
- plttikz files: optional, inject tikz code before or after the code generated by gnuplot. It allows to draw in plots!
- tex file: we decorate the plttikz file with some packages and a document class (standalone) to have a cropped image
- pdf file: the tex file compiled with pdflatex
- eps file: pdf to eps
- svg file: pdf to svg
Others
Any other chain for another tool can be implemented, such as matplotlib in python, which has a tikz terminal too.
Implementation¶
My first implementation (around 2007) was based on shell scripts and makefile. Quickly coded, but not easy to maintain and the code tend to become hard to read very rapidly.
The second implementation (around 2011) used waf, a build to in python. The idea was to reuse something existing rather than writing from scratch a workflow. However, in practice, waf is not full adapted for the workflow I need. I made a working version I used for almost 4-5 years, I found interesting features (colored output, src and build separated, export function) but the addition of new workflow would require a lot of energy.
Then, I arrived to write a third version, from scratch since I know perfectly what I need:
- a database to record what must be recompiled based on modifications
- a detector to guess the right rule to apply (based on file formats)
- a set of rules to build the figure
- a nice output
How to install?¶
Package manager¶
- [Archlinux](https://aur.archlinux.org/packages/scifig/)
Files for po4a for translations (i18n)¶
Po4a part (optional)
According to your distribution, move pm files located in po4a/ to
- /usr/share/perl5/vendor_perl/Locale/Po4a
- or /usr/share/perl5/Locale/Po4a (debian)
libscifig API¶
Tasks¶
A Task
is composed of the following steps:
- Transform the source files to a tex file
- convert tex to pdf with
_tex_to_pdf()
- convert pdf to svg with
_pdf_to_svg()
- convert pdf to eps with
_pdf_to_eps()
- convert pdf to png with
_pdf_to_png()
Step 1 can be complex and could require several sub-steps.
Thus, the role of _pre_make()
is to do all these sub-steps.
Steps 2 to 5 usually do not depend on the initial type of the task.
The function make()
do all of them.
Each format has its own export function. The function export()
exports all of them.
-
class
task.
GnuplotTask
(filepath, datafiles=[], tikzsnippet=False, tikzsnippet1=False, tikzsnippet2=False, build='build')[source]¶ Bases:
task.Task
Gnuplot Task manager.
-
check_dependencies
(db)¶ Check if dependencies have been modified.
Parameters: db – DataBase instance
-
check_targets
(db, pdf_only=False)¶ Check if targets have been modified.
Parameters: - db – DataBase instance
- pdf_only – Check only the status for pdf
-
export
(db, dst='/tmp')¶ Export built files.
Parameters: - db – DataBase instance
- dst – filepath of the destination directory
-
export_eps
(dst='/tmp')¶ Export built EPS files.
Parameters: dst – filepath of the destination directory
-
export_pdf
(dst='/tmp')¶ Export built PDF files.
Parameters: dst – filepath of the destination directory
-
export_png
(dst='/tmp')¶ Export built png files.
Parameters: dst – filepath of the destination directory
-
export_svg
(dst='/tmp')¶ Export built SVG files.
Parameters: dst – filepath of the destination directory
-
export_tex
(dst='/tmp')¶ Export TEX files.
Parameters: dst – filepath of the destination directory
-
get_name
()¶ Return the name of the task.
-
make
(db)¶ Compile the figure in all formats.
-
make_pdf
(db)¶ Compile the figure in pdf.
-
-
class
task.
Task
(filepath, build='build')[source]¶ Bases:
object
Parent Task manager.
Parameters: - filepath – filepath of the main file
- build – relative filepath of the build dir
-
check_dependencies
(db)[source]¶ Check if dependencies have been modified.
Parameters: db – DataBase instance
-
check_targets
(db, pdf_only=False)[source]¶ Check if targets have been modified.
Parameters: - db – DataBase instance
- pdf_only – Check only the status for pdf
-
export
(db, dst='/tmp')[source]¶ Export built files.
Parameters: - db – DataBase instance
- dst – filepath of the destination directory
-
export_eps
(dst='/tmp')[source]¶ Export built EPS files.
Parameters: dst – filepath of the destination directory
-
export_pdf
(dst='/tmp')[source]¶ Export built PDF files.
Parameters: dst – filepath of the destination directory
-
export_png
(dst='/tmp')[source]¶ Export built png files.
Parameters: dst – filepath of the destination directory
-
export_svg
(dst='/tmp')[source]¶ Export built SVG files.
Parameters: dst – filepath of the destination directory
-
class
task.
TikzTask
(filepath, datafiles=[], build='build')[source]¶ Bases:
task.Task
Tikz Task manager.
-
check_dependencies
(db)¶ Check if dependencies have been modified.
Parameters: db – DataBase instance
-
check_targets
(db, pdf_only=False)¶ Check if targets have been modified.
Parameters: - db – DataBase instance
- pdf_only – Check only the status for pdf
-
export
(db, dst='/tmp')¶ Export built files.
Parameters: - db – DataBase instance
- dst – filepath of the destination directory
-
export_eps
(dst='/tmp')¶ Export built EPS files.
Parameters: dst – filepath of the destination directory
-
export_pdf
(dst='/tmp')¶ Export built PDF files.
Parameters: dst – filepath of the destination directory
-
export_png
(dst='/tmp')¶ Export built png files.
Parameters: dst – filepath of the destination directory
-
export_svg
(dst='/tmp')¶ Export built SVG files.
Parameters: dst – filepath of the destination directory
-
export_tex
(dst='/tmp')¶ Export TEX files.
Parameters: dst – filepath of the destination directory
-
get_name
()¶ Return the name of the task.
-
make
(db)¶ Compile the figure in all formats.
-
make_pdf
(db)¶ Compile the figure in pdf.
-
database¶
-
class
database.
DataBase
(db_path)[source]¶ Bases:
object
Custom class to manipulate a json database.
Parameters: db_path – filepath of the database.
detector¶
-
detector.
detect_datafile
(plt, root)[source]¶ Detect datafiles associated with a plt file.
Parameters: - plt – plt filepath
- root – root filepath
Returns: list of filepath starting at root