README.org

cart.el : CAlibrated inteRactive coordinates for Tikz

An emacs package to help streamline the preparation of beamer presentations with tikz graphical elements. The user can input tikz coordinates through mouse clicks which get automatically transformed into tikz-sensible coordinates. These include the simplest operations of node insertions to transformations (rotations/scaling/translations) to actually drawing curves with tikz!

Introduction

cart.el defines interactive elisp functions for obtaining coordinates for tikz commands graphically following a calibration.

It must be noted that although cart.el improves the interaction/feedback while using Tikz, it is still not exactly WYSIWYG, since the latex file has to be compiled after each insertion of coordinates.

UPDATE VER 0.2 : Cart.el now supports a basic Graphical Front-End based on artist-mode!

Appeal to contributors : I am pretty new to elisp development so I’d appreciate any feedback on the package and ways to improve/standardize it.

TODO : Video Demo. I’m waiting for the package to stabilize before I make any proper publicity/put it on MELPA. It’s become a staple for me, however.

Configuration

Configuration is pretty standard. Adding these lines to your emacs startup is all that is needed:

(add-to-list 'load-path "<root-directory-of-cart.el>")
(require 'cart)
(add-hook 'LaTeX-mode-hook 'cart-mode)

Usage

Usage is quite straightforward. During the first time, it’s recommended to follow these steps:

1. Calibration: Open a latex buffer along with its pdf output with code that plots an arbitrary line (=AucTex= & =pdf-tools= is recommended, but not required). For instance, the following tikz code plots a line from (0,0) to (2,2) (see figure below).

   \begin{tikzpicture}
     \pgftransformshift{\pgfpointanchor{current page}{center}}
   
     \draw[->] (0,0) -- (2,2);
   \end{tikzpicture}
       

   

   In order to calibrate the cart.el, call the function cart-calibrate (default keybinding set to C-x a c) and follow the prompts. It will ask the X & Y coordinates, followed by a prompt to click on the location in the buffer, for the two points.

   /Note/: It is not necessary to conduct calibration explicitly each time if the buffer sizes and views will be the same. Once this calibration is done, go to customize-group -> cart and save the values of Cart Xy_0sl in the customization UI as below.

   

2. Insertion: Point: You can insert the coordinates of any point at the current point by calling cart-insert-point (default kbd: C-x a p). It will prompt the user to click on any point on the screen. The pixel coordinates from the read-event will be transformed using the calibration conducted above.
3. Insertion: Tikz Draw: Interactive tikz-draw can be initiated by calling cart-tikz-draw (default kbd: C-x a d). It will first prompt the user for “draw options” (string options to be passed as \draw[options]) and “node options” (string options to be passed as (pt_x, pt_y)options) before prompting the user to start clicking the desired points. The node options (if given) will be applied to all the points. All the points will be jointed using ”--” (implying straight lines). The selection can be stopped by triggering any event other than down-mouse-1=(left click), hitting =RET for example. cart-tikz-draw also supports the specification of local tangents by clicking and dragging through the tikz controls interface.
4. Insertion: Tikz Node: Interactive tikz-nodes can be initiated by calling cart-tikz-node (default kbd: C-x a n). It will first prompt the user for “node options” (string options to be passed as \node[options]) and “node value” (string value to be passed as \node[...] at (pt_x, pt_y) {value};), before prompting the user to choose the point (only one point in this case).
5. Insertion: Tikz circle: Interactive tikz-draw initiated by calling cart-tikz-circle (default kbd: C-x a e) and a circle is drawn through the two points the user clicks & drags (or clicks sequentially). The radius defaults to the mean point.
6. Insertion: Tikz Draw Plot Coordinates: Interactive tikz-draw plot coordinates can be initiated by calling cart-tikz-coordinates (default kbd: C-x a c). It will first prompt the user for “draw options” (string options to be passed as \draw[options]) before prompting the user to start clicking the desired points. The argument [smooth] will be passed to plot. The selection can be stopped by triggering any event other than down-mouse-1=(left click), hitting =RET for example.
7. Transformation: Translation: Either start by choosing a region (ensure you start from the first “" statement and select until the last “;” character) or having point inside any Tikz/Pgf command statement bound by “" & “;”. Now call cart-translate-tikz (default kbd: C-x a t) and select the start and end points by either dragging or clicking sequentially.
8. Transformation: Rotation: Start just like for translation. Now call cart-rotate-tikz (default kbd: C-x a r) and select the center point, and start-end points by dragging/clicking sequentially. A prompt will come asking if the node contents should also be rotated (handled through the Tikz rotate fields of the nodes). Rotation will be conducted so as to move the start point feature to the end point.
9. Transformation: Scaling: Start just like for translation. Now call cart-scale-tikz (default kbd: C-x a s) and select the reference point, and start-end points by dragging/clicking sequentially. A prompt will come asking if the node contents should also be rotated (handled through the Tikz rotate fields of the nodes). Scaling will be conducted so as to move the start point feature to the end point.
10. Transformation: Move single point: Start with the point inside the tikzpicture environment corresponding to the figure you’re looking at. Now call cart-tikz-move-point (default kbd: C-x a m). A prompt will ask you to choose a point and drag it to its target location.
11. Transformation: Delete single point: Start similar to moving and call cart-tikz-delete-point (default kbd: C-x a k). Select the desired point to delete it.

Keybinding	Command	Description
C-x a	cart-keymap-prefix	Prefix. Not callable.
C-x a C	cart-calibrate	Initiate Calibration.
Insertion
C-x a p	cart-insert-point	Insert single point.
C-x a n	cart-tikz-node	Insert Tikz node.
C-x a d	cart-tikz-draw	Insert Tikz draw.
C-x a e	cart-tikz-circle	Insert Tikz circle (with draw).
C-x a c	cart-tikz-coordinates	Insert Tikz coordinates.
Transformation
C-x a t	cart-translate-tikz	Translate region/statement.
C-x a r	cart-rotate-tikz	Rotate region/statement.
C-x a s	cart-scale-tikz	Scale region/statement.
C-x a m	cart-tikz-move-point	Move selected point.
C-x a k	cart-tikz-delete-point	Delete selected point.

Usage of the artist-mode Graphical Feedback

1. Cart.el supports a minimalistic ascii-based front-end for visual user feedback.
2. This can be enabled by calling the interactive function cart-visual-toggle.
3. Note that calibration needs to be done afresh for this.
4. This works by creating a transparent frame right on top of the current frame (opaque foreground). This feature is only supported by emacs 29.1 and later so is not enabled by default.
5. Look into the customization to see how to customize this.

Examples

artist-mode Graphical Feedback

Personal Tips for Beamer

Since it is often the case in presentations to want graphical objects “pop-up” independent of the remaining content on the slide, I use the following preamble in each of my tex files:

\usepackage{tikz}

\usetikzlibrary{shapes.arrows,shapes.callouts,patterns,decorations.pathmorphing,
  decorations.markings,shapes,arrows.meta,positioning}
\tikzset{
  invisible/.style={opacity=0},
  visible on/.style={alt={#1{}{invisible}}},
  alt/.code args={<#1>#2#3}{%
    \alt<#1>{\pgfkeysalso{#2}}{\pgfkeysalso{#3}} % \pgfkeysalso doesn't change the path
  },
}

The above enables the “visible on” property for all the tikz objects, where you can specify overlay information.

I often have my tikzpicture environment setup in the following fashion so that its centered at the middle of the page. An example may be found in the test folder.

\begin{tikzpicture}[overlay,remember picture]
  \pgftransformshift{\pgfpointanchor{current page}{center}}

  % Insert draw/node commands here

\end{tikzpicture}

Possible Improvements

1. Integration of Tikz/Pgf variables.
2. cart-scale-tikz currently doesn’t scales circle radius fields manually. Something more general would be better.
3. Units are currently not supported for the node attributes (like specifying radius as 3pt). These will be considered correctly only if provided along with a decimal point. This is an inconvenience that needs to be addressed.
4. Some mechanism simulating graphical feedback. Two ideas for this:
   1. We currently support spaning a transparent frame under artist-mode and providing ASCII feedback on it. This works quite nicely on emacs 29.1.
   2. Using GNOME’s built-in mouse location feature for mouse click highlights? I am hesitant to incorporate this because this becomes platform dependent in this case. Calling the following command, for instance, will make the mouse location get highlighted each time lCtrl is pressed. This is an out-of-emacs solution, but sounds simple, if setup well.

      gsettings set org.gnome.desktop.interface locate-pointer true
              

5. Using the “:width” property (and other properties) of the png image (pdf-tools displays the pages as png images) to use pdf-relative coordinates to add robustness across window size changes.

Necessary Bugfixes

No currently active bugs! ^_^

Desirable features

1. It would be nice to have a “draw shape around objects” feature.
2. It would be good to have cart.el aware of the different “objects” in a drawing.
3. Incorporate includegraphics trim into the ecosystem.

Recommended Reading/Interesting Repositories

1. The documentation of Tikz & PGF.
2. The el-easydraw package by misohena is WYSIWYG implementation of SVG drawing in emacs.
3. The pymupdf-mode implements a version of WYSIWYG drawing using python and zathura. I personally feel that a more elegant solution using pure elisp is possible.

Some quotes from around

With TikZ you get all the advantages of the “TEX-approach to typesetting” for your graphics: quick creation of simple graphics, precise positioning, the use of macros, often superior typography. You also inherit all the disadvantages: steep learning curve, no wysiwyg, small changes require a long recompilation time, and the code does not really “show” how things will look like.

– Tikz/PGF Manual