https://github.com/nidish96/cart.el

cart.el provides convenient function definitions meant to be used in tandem with auctex and some pdf viewer within emacs (like pdf-tools). The main purpose is to speed up inserting and editing graphical objects using Tikz/Pgf on latex documents/(beamer) presentations.
https://github.com/nidish96/cart.el

auctex beamer emacs latex pdf-tools tikz tikz-editor

Last synced: 5 days ago
JSON representation

cart.el provides convenient function definitions meant to be used in tandem with auctex and some pdf viewer within emacs (like pdf-tools). The main purpose is to speed up inserting and editing graphical objects using Tikz/Pgf on latex documents/(beamer) presentations.

• Host: GitHub
• URL: https://github.com/nidish96/cart.el
• Owner: Nidish96
• Created: 2023-04-03T11:58:47.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-21T20:13:00.000Z (9 months ago)
• Last Synced: 2024-04-22T01:03:39.220Z (9 months ago)
• Topics: auctex, beamer, emacs, latex, pdf-tools, tikz, tikz-editor
• Language: TeX
• Homepage:
• Size: 2.03 MB
• Stars: 5
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.org

Awesome Lists containing this project

README

        
#+TITLE: =cart.el= : CAlibrated inteRactive coordinates for Tikz

#+STARTUP: indent

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:

#+begin_src emacs-lisp :tangle yes

  (add-to-list 'load-path "")

  (require 'cart)

  (add-hook 'LaTeX-mode-hook 'cart-mode)

#+end_src

* 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 ([[https://www.gnu.org/software/auctex/][=AucTex=]] & [[https://github.com/vedang/pdf-tools][=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_src latex

     \begin{tikzpicture}

       \pgftransformshift{\pgfpointanchor{current page}{center}}

       \draw[->] (0,0) -- (2,2);

     \end{tikzpicture}

   #+end_src

   #+CAPTION: Sample of the line drawn by the code above

   #+ATTR_HTML: :width 800px

   #+ATTR_LATEX: :width 400px

   #+ATTR_ORG: :width 100px

   [[./figs/fig1.png]]

   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.

   #+CAPTION: Saving calibration in the customization UI

   #+ATTR_HTML: :width 600px

   #+ATTR_LATEX: :width 200px

   #+ATTR_ORG: :width 50px

   [[./figs/fig2.png]]

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.

#+CAPTION: Default Keybindings

| 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

#+CAPTION: Example 1 of a graphic drawn using =tikz= and =cart.el=

#+ATTR_HTML: :width 800px

#+ATTR_LATEX: :width 400px

#+ATTR_ORG: :width 100px

[[./figs/fig3.png]]

#+CAPTION: Example 2 of a graphic drawn using =tikz= and =cart.el=

#+ATTR_HTML: :width 800px

#+ATTR_LATEX: :width 400px

#+ATTR_ORG: :width 100px

[[./figs/fig4.png]]

*** =artist-mode= Graphical Feedback

#+CAPTION: Example 3 of a graphic drawn using =tikz= and =cart.el=. Visualized against artist front-end.

#+ATTR_HTML: :width 400px

#+ATTR_LATEX: :width 300px

#+ATTR_ORG: :width 100px

[[file:figs/fig5a.png]]

#+CAPTION: Example 4 of a graphic drawn using =tikz= and =cart.el=. Visualized against artist front-end.

#+ATTR_HTML: :width 200px

#+ATTR_LATEX: :width 100px

#+ATTR_ORG: :width 100px

[[file:figs/fig5b.png]]

#+CAPTION: Example 5 of a graphic drawn using =tikz= and =cart.el=. Visualized against artist front-end.

#+ATTR_HTML: :width 300px

#+ATTR_LATEX: :width 200px

#+ATTR_ORG: :width 100px

[[file:figs/fig5c.png]]

** 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:

#+begin_src latex

  \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

    },

  }

#+end_src

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 [[file:test/test.tex][test folder]].

#+begin_src latex

  \begin{tikzpicture}[overlay,remember picture]

    \pgftransformshift{\pgfpointanchor{current page}{center}}

    % Insert draw/node commands here

  \end{tikzpicture}

#+end_src

* 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.

      #+begin_src sh

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

      #+end_src

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 [[https://pgf-tikz.github.io/pgf/pgfmanual.pdf][documentation of Tikz & PGF]].

2. The [[https://github.com/misohena/el-easydraw][el-easydraw]] package by [[https://github.com/misohena][misohena]] is WYSIWYG implementation of SVG drawing in emacs.

3. The [[https://github.com/dalanicolai/pymupdf-mode.el][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

#+begin_quote Tikz/PGF Manual

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

#+end_quote