Thomashk0's web pages

Some Inkscape Tips

2024-08-25T00:00:00+02:00

As a researcher, having some basic knowledge of a vector graphic tool is a valuable skill. Among the variety of options, Inkscape is a nice open-source project for creating and editing SVG files.

This tool is quite powerful, you can do almost any sort of 2-D vector drawing with it. Such flexibility comes with a cost: there is a steep learning curve for the tool and it can take some efforts to make simple things.

Is it worth investing time in learning Inkscape? To be honest, I don't know. If you need a quick solution to make drawings, you will probably get the job done faster with things like draw.io, excalidraw, or others.

I learned Inkscape because it was the best open-source option at the time I started my career. But I do not regret it. I like to have an offline open-source solution for my drawings that is git-friendly. With a bit of practice, you can produce any kind of diagrams (more that enough for scientific papers). You will also not be afraid to edit SVG files when needed (e.g., stripping a you-don't-know-why-it-is-there margin from matplotlib to make your paper fit the page limit, 5 minutes before a deadline).

In this post, I show some tip to improve the Inkscape experience.

Basic Configuration

For scientific papers, some sort of alignment is always welcome in your illustrations! If find that using a grid is mandatory. You want to do two things:

Display the grid (Press "#" for switching it on/off). Note that you can customize the grid size. There are two grids, primary and secondary. It can be useful to change the spacing and colors in some situations.
Enable snapping (Press "%" for switching it on/off), so that items like boxes or text will automatically snap to the grid. You can customize how snapping behaves: I find it easier to snap to borders of elements. You want to enable snapping for all items (boxes, text, paths).

This way, you can ensure consistent spacing of items.

Screenshot showing the grid configuration. Aligning items with snapping is so satisfying :)

Use Automatic Alignment

Inkscape has automatic alignment, this feature can save you many clicks! I tend to draw everything and align everything at the end.

Press CTRL-ALT-A to open the alignment pane, then you can select items and align them in different ways.

The important thing to remember here is that alignment is done on the first item of the selection.

Copy style

You do not want to manually replicate style of items.

Once you styled an item (box or whatever), you can copy it with CTRL-C, then you can select a bunch of other items and press CTRL-SHIFT-V, this will apply the style of the first item to your selection.

Conversion

For converting SVG to other formats, I usually export the drawing region. This requires you to properly resize the document to your drawing area. The Inkscape command is quite handly and has tons of options for exporting .svg files.

Export to PDF:

$ inkscape --export-text-to-path -D -o output.pdf input.svg

The --export-text-to-path option is very important. As suggested, it transforms text to paths. Otherwise, text is rendered by the PDF rendering engine and fonts may be missing. By passing this flag, you will have a consistent rendering of your drawings.

Export to PNG:

$ inkscape -D -d 300 -o output.png input.svg

Here, the DPI parameter is set 300.

With release 1.0, the Inkscape command line changed. Here are the versions of those commands for older Inkscape:

$ inkscape --export-text-to-path -D -A output.pdf input.svg
$ inkscape -D -d 300 -e output.png input.svg

Makefile Snippet

A big selling point for Inkscape is that you can save your .svg files inside a git repository and generate exports at build-time using the commands shown in the previous section. This is super convenient for scientific papers.

Note

Once you generate a final version of your paper, I highly recommend saving the figures in some way (I usually add them to git). Inkscape updates can change the rendering. This happened to me several time: the layout of your paper is completely broken because the images generated are not exactly the same (e.g., extra margin).

Then, if you want to be 100% reproducible, snapshot your exported figures!

Here is a snippet that you can integrate in your makefile to automatically build figures.

.svg source files are assumed to be in directory figs/svg/.
Type make figs/name_of_fig.pdf to compile name_of_fig.pdf into PDF.
Type make figs/name_of_fig.png to compile name_of_fig.png into PNG.

INKSCAPE ?= inkscape
INKSCAPE_FLAGS ?=
INKSCAPE_FLAGS += --export-text-to-path
INKSCAPE_VERSION_1 := $(shell inkscape --version | grep -o -E 'Inkscape 1\.[0-9]+')

figs/%.pdf: figs/svg/%.svg
ifeq ($(INKSCAPE_VERSION_1),) # Inkscape < 1.0
    $(INKSCAPE) $(INKSCAPE_FLAGS) -D -A $@ $<
else
    $(INKSCAPE) $(INKSCAPE_FLAGS) -D -o $@ $<
endif

figs/%.png: figs/svg/%.svg
ifeq ($(INKSCAPE_VERSION_1),) # Inkscape < 1.0
    $(INKSCAPE) $(INKSCAPE_FLAGS) -D -d 300 -e $@ $<
else
    $(INKSCAPE) $(INKSCAPE_FLAGS) -D -d 300 -o $@ $<
endif

Hiding Layers for Simple Animations

You can organize your .svg file into multiple layer.

Sometimes, it can be nice to export only some selected layers. Imagine a file having some background image and some layers containing arrows and text annotations. By exporting a subset of layers, it is possible to create an animation that you can include in a slide deck for example.

I have a small script here (~100 lines of Python, without any external dependency) that I use all the time.

Hiding some layers is as simple as:

./exportlayers --hide text_layer_1,text_layer_2 -o fig_background_only.pdf fig.svg

Making you diagram `draw.io`-ish

If you are afraid that your diagrams will not look as cool as those of your friends made with draw.io, here are a few tips to mimic the draw.io style:

Enable rounding of borders in "Stroke style", even add a small radius to the corner of boxes.
Make your borders the same colors of the boxes, but make them slightly darker: show colors in HSL, and reduce the lightness (L).
Pick a "good-looking" color palette on google and stick to it for your project.

Restyling of the diagram shown in previous section

Ray Tracing and Refraction

2022-12-28T00:00:00+01:00

A few weeks ago I was following Peter Shirley’s awesome “Ray Tracing in One Week End” book. Everything went fine until I reached dielectric materials, where I started to obtain really weird pictures. From there, I had to fully re-check the ray tracer. This was both painful and beneficial, since it forced me to dig into every details of the ray tracer. The formulas for refraction are not really explained in the book. So, I decided to write a more detailed explanation in this post. Internalizing this proof actually lead me to the bug in my code, I hope that can help.

Here is a small widget that implements the formulas described in this post.

Refractive Indice ni
Refractive Indice nr
Angle In		40°
Angle Out

Overview

Refraction describes how a ray behaves when crossing materials. We consider the setup depicted on Figure 1, where a ray intersects different materials (e.g., from air to water). The materials have different refractive indices \(n_{i}\) and \(n_{r}\). Let \(\vec{i}\) be the incident ray, \(\vec{r}\) the refracted ray and \(\vec{n}\) the surface normal. The question is: how can we express \(\vec{r}\) in function of \(\vec{i}\) and \(\vec{n}\) and the refractive indices?

Figure 1: Typical Refraction Setup

We make the following assumptions:

the normal vector is always oriented against the incident ray, formally \(\langle\vec{i},\,\vec{n}\rangle<0\),
all vectors are normalized, \(\|\vec{i}\|=\|\vec{r}\|=\|\vec{n}\|=1\).

The relation between \(\theta_{i}\) and \(\theta_{r}\) is given by Snell’s law, which states that:

\begin{equation*} n_{i}\sin\theta_{i}=n_{r}\sin\theta_{r}\label{eq:snell_law} \end{equation*}

Note that there cannot be refraction in every configuration. For refraction to be possible, we need to have:

\begin{equation*} \frac{n_{i}}{n_{r}}\sin\theta_{i}<1. \end{equation*}

When this condition is not satisfied, the ray is reflected.

The Refraction Formula

Ok, now lets see how we can compute \(\vec{r}\) from \(\vec{i}\) and \(\vec{n}\). The trick is to decompose \(\vec{r}\) as follows:

\begin{equation*} \vec{r}=\vec{r_{||}}+\vec{r_{\perp}} \end{equation*}

Where is \(\vec{r}_{||}\) is the projection of \(\vec{r}\) on \(\vec{n}\) and \(\vec{r_{\perp}}\) the projection on the orthogonal of \(\vec{n}\) in the plane generated by \(\vec{i}\) and \(\vec{n}\) . This decomposition expands as follows:

\begin{equation*} \begin{aligned} \vec{r} & = & \underbrace{\langle\vec{r},\,\vec{n}\rangle\vec{n}}_{\vec{r_{||}}}+\underbrace{(\vec{r}-\langle\vec{r},\,\vec{n}\rangle\vec{n})}_{\vec{r_{\perp}}}\label{eq:r_expansion}\end{aligned} \end{equation*}

It is easy to check that the right term is indeed orthogonal to \(\vec{n}\) (the dot product with \(\vec{n}\) is zero). Another way to express \(\vec{r}_{\perp}\) is through a cross product:

\begin{equation*} \vec{r}_{\perp}=(\vec{r}-\langle\vec{r},\,\vec{n}\rangle\vec{n})=(\vec{r}\times\vec{n})\times\vec{n}. \end{equation*}

We can expand \(\vec{i}\) in the same way we did for \(\vec{r}\).

\begin{equation*} \begin{aligned} \vec{i} & = & \underbrace{\langle\vec{i},\,\vec{n}\rangle\vec{n}}_{\vec{i_{||}}}+\underbrace{(\vec{i}-\langle\vec{i},\,\vec{n}\rangle\vec{n})}_{\vec{i_{\perp}}}\end{aligned} \end{equation*}

And we also have (keep this equality in mind, we will reuse it by the end of the proof):

\begin{equation*} \vec{i}_{\perp}=(\vec{i}-\langle\vec{i},\,\vec{n}\rangle\vec{n})=(\vec{i}\times\vec{n})\times\vec{n}\label{eq:i_perp} \end{equation*}

Now here is the trick I missed when trying to work out this proof: \(\vec{r}\) is in the plane generated by \(\vec{i}\) and \(\vec{n}\). In other words, \(\vec{i}\times\vec{n}\) and \(\vec{r}\times\vec{n}\) are colinear and as a bonus, they are linked by Snell’s law. The cross product of two vector is defined as:

\begin{equation*} \vec{i}\times\vec{n}=\|\vec{i}\|\|\vec{n}\|\sin\theta_{i}\vec{k}. \end{equation*}

Here, I introduced \(\vec{k}\) which is the orthogonal vector to the plane generated by \(\vec{i}\) and \(\vec{n}\). Similarly, for \(\vec{r}\) we have:

\begin{equation*} \vec{r}\times\vec{n}=\|\vec{r}\|\|\vec{n}\|\sin\theta_{r}\vec{k}. \end{equation*}

If we assume that \(\|\vec{i}\|=\|\vec{r}\|=1\), we can write:

\begin{equation*} \begin{aligned} \vec{r}\times\vec{n} & =\sin\theta_{r}\vec{k}\nonumber \\ & =\frac{n_{i}}{n_{r}}\sin\theta_{i}\vec{k} & \text{(Using Snell's law)}\nonumber \\ & =\frac{n_{i}}{n_{r}}\vec{i}\times\vec{n}.\end{aligned} \end{equation*}

Awesome! We are ready to expand \(\vec{r}\). Lets review the decomposition of \(\vec{r}\):

\begin{equation*} \begin{aligned} \vec{r} & = & \vec{r}_{||} + \vec{r}_{\perp}\\ & = & \langle\vec{r},\,\vec{n}\rangle\vec{n}+(\vec{r}\times\vec{n})\times\vec{n}.\end{aligned} \end{equation*}

We can now expand each term. Lets start with the left one, \(\vec{r}_{||}\):

\begin{equation*} \begin{aligned} \langle\vec{r},\,\vec{n}\rangle\vec{n} & =-\langle-\vec{r},\,\vec{n}\rangle\vec{n}\\ & =-\cos\theta_{r}\vec{n}\\ & =-\sqrt{1-\sin^{2}\theta_{r}}\vec{n}\\ & =-\sqrt{1-\left(\frac{n_{i}}{n_{\theta}}\right)^{2}\sin^{2}\theta_{i}}\vec{n}\\ & =-\sqrt{1-\left(\frac{n_{i}}{n_{\theta}}\right)^{2}\left(1-\cos^{2}\theta_{i}\right)}\vec{n}\\ & =-\sqrt{1-\left(\frac{n_{i}}{n_{\theta}}\right)^{2}\left(1-\langle-\vec{i},\,\vec{n}\rangle^{2}\right)}\vec{n}\end{aligned} \end{equation*}

In the first line, we use the basic trigonometry equation between sines and cosines, \(\cos^{2}\theta+\sin^{2}\theta=1\). In the second line, we apply Snell law. In the third line, we apply again some basic trigonometry again. The last step uses the fact that \(\cos\theta_{i}=\langle-\vec{i},\,\vec{n}\rangle\). So, we have expressed \(\vec{r_{\perp}}\) only from \(\vec{i}\) and \(\vec{n}\).

Now, it is time to expand \(\vec{r_{\perp}}\): .

\begin{equation*} \begin{aligned} (\vec{r}\times\vec{n})\times\vec{n} & =\left(\frac{n_{i}}{n_{r}}\vec{i}\times\vec{n}\right)\times\vec{n}\\ & =\frac{n_{i}}{n_{r}}\left(\vec{i}\times\vec{n}\right)\times\vec{n}\\ & =\frac{n_{i}}{n_{r}}(\vec{i}-\langle\vec{i},\,\vec{n}\rangle\vec{n})\\ & =\frac{n_{i}}{n_{r}}(\vec{i}+\langle-\vec{i},\,\vec{n}\rangle\vec{n})\end{aligned} \end{equation*}

On the first line, we rewrite the cross product, thanks to Snell's law. On the second line, we move out the scalar constant and on the last line, we use the relation shown previously.

Lets define \(\mu=\frac{n_{i}}{n_{r}}\), then \(\vec{r}\) can be written as:

\begin{equation*} \begin{aligned} \vec{r} & =\vec{r_{||}}+\vec{r}_{\perp}\\ & =-\sqrt{1-\mu^{2}\left(1-\langle-\vec{i},\,\vec{n}\rangle^{2}\right)}\vec{n}+\mu(\vec{i}+\langle-\vec{i},\,\vec{n}\rangle\vec{n})\\ & =\left(\mu\langle-\vec{i},\,\vec{n}\rangle-\sqrt{1-\mu^{2}\left(1-\langle-\vec{i},\,\vec{n}\rangle^{2}\right)}\right)\vec{n}+\mu\vec{i} \end{aligned} \end{equation*}

Back to the Code

Now, the code shown in the book should make more sense.

vec3 refract(const vec3& uv, const vec3& n, double etai_over_etat)
{
    auto cos_theta = fmin(dot(-uv, n), 1.0);
    vec3 r_out_perp =  etai_over_etat * (uv + cos_theta*n);
    vec3 r_out_parallel = -sqrt(fabs(1.0 - r_out_perp.length_squared())) * n;
    return r_out_perp + r_out_parallel;
}

Well, if you look carefully, the r_out_parallel does not match with the expression of \(\vec{r}_{||}\). The author applied Pythagoras' theorem (assuming the vector returned is a unit vector).

\begin{equation*} ||\vec{r}||^2 = ||\vec{r}_{||}||^2 + ||\vec{r}_{\perp}||^2 \end{equation*}

So,

\begin{equation*} ||\vec{r}_{||}|| = \pm \sqrt{1 - ||\vec{r}_{\perp}||^2} \end{equation*}

Since we know that \(\vec{r}_{||}\) is oriented against \(\vec{n}\), we can write:

\begin{equation*} \vec{r}_{||} = -\sqrt{1 - ||\vec{r}_{\perp}||^2}\vec{n} \end{equation*}

Pfew, while there are no fancy math involved, understanding the final refraction program was much more involved than what I initially though. Given the quantity of boring equation, I definitely understand why the author did not include them in its book!

Useful References

Here are some references that helped me debug refraction:

Survival Kit for C Programmers (Macros)

2022-11-24T00:00:00+01:00

I realized that in my C projects I always need the same macros over and over. I thought it would be interesting to centralize them somewhere and document them.

The macros presented here should work with any recent GCC or LLVM compiler. I do not guarantee they will work on all compiler/architectures.

If you want to go further, I highly recommend you to take a look at the Hedley project. Hedley provides a huge amount of features and is platform generic.

The code for this post (with some additional examples) is available here.

Sizeof Arrays

One lacking feature in C is the ability to retrieve the size of fixed-size arrays. The glorious sizeof operator, returns the full length in bytes of the target object. The COUNT_OF macro shown below solves this issue.

/// Retrieve the number of items in a array.
#define COUNT_OF(x) (sizeof(x) / sizeof(x[0]))

You can use it as follows:

double local_array[3] = {1.0, 2.0, 3.0};

assert(COUNT_OF(local_array) == 3);
for (int k = 0; k < COUNT_OF(local_array); k++) {
    // do some stuff.
}

If compatibility with C++ is needed, I suggest you pick a safer version of this macro (see this stack overflow post).

Basic Type Generic Operations

MIN, MAX emulates a type generic min and max operations between two variables.

#define MIN(a, b) ((a) > (b)) ? (b) : (a)
#define MAX(a, b) ((a) < (b)) ? (b) : (a)

Another useful one is ABS, which emulates a type generic absolute value.

#define ABS(x) (((x) < 0) ? -(x) : (x))

Another function that appears quite frequently in my code bases is a check for a power of two. It can be implemented with some bit tricks.

#define is_power_of_two(x) ((x) && !((x) & ((x)-1)))

Compiler Hints

There are countless compiler-specific macros that allow to give optimization hints. I only include the ones I use in almost every project.

The most useful ones are LIKELY and UNLIKELY, used to indicate the compiler the expected outcome of a boolean expression.

#define LIKELY(x) __builtin_expect((x), 1)

#define UNLIKELY(x) __builtin_expect((x), 0)

I am not entirely sure that the compiler will always consider those annotations. I generally use them in two situations.

The first situation is in performance critical code, where I want to suggest "really hard" to the compiler what is the hot path in our program. It is worth mentioning that a better approach for large codebases may be to use profile guided optimizations.

The second situation, is when I am doing error checks. I find those annotations conveniently document the unlikely nature of failures.

int foo_can_fail() {
    if (UNLIKELY(bar_acuda())) {
        return -1;
    }
    if (UNLIKELY(bar_tabac())) {
        return -2;
    }
    return 0;
}

Another macro I use very often is ALIGNED, mostly to align "important" data on cache line boundaries.

#define ALIGNED(x) __attribute__((aligned(x)))

You can use it as follows:

// In variable declaration.
static ALIGNED(16) int array[8] = {};

// In structure definition.
struct coords {
     double x;
     double y;
} ALIGNED(16);

Another powerful macro is ASSUME, we give it predicate that the compiler can exploit in its optimizations phases.

#define ASSUME(cond)                  \
    do {                              \
        if (!(cond))                  \
            __builtin_unreachable();  \
    } while (0)

I typically use this macro to specify constraints on array sizes, to make loop optimizations (unrolling, auto-vectorization) more aggressive. For example:

void add_vec(int* data, size_t data_len, int x) {
    ASSUME(data_len >= 16);
    ASSUME((data_len % 16) == 0);
    for (size_t k = 0; k < data_len; k++) {
        data[k] += x;
    }
}

Here is a side-by-side comparison of the assembly code (gcc -O3) with and without the ASSUME annotation. It is pretty clear that the ASSUME macro allowed to drastically simplify the loop.

Assembly code with and without the ASSUME macro.

But be careful with ASSUME, it is very easy to shoot yourself in the foot with this macro! If the assumption given to the compiler is not true, bad things will happen.

Minimalistic Logging

This topic will be covered in greater details in another post.

I like to have really simple printf-based tracing in my applications (usually enable only in debug builds).

Basically, I write a simple wrapper around fprintf with the following prototype:

int
survival_log(
    long level,
    const char* file,
    const char* func,
    long line,
    const char* fmt,
    ...) __attribute__((format(printf, 5, 6)));

A minimal implementation of this function will look something like this:

#include <stdio.h>
#include <stdarg.h>

int
survival_log(
    long level,
    const char* file,
    const char* func,
    long line,
    const char* fmt,
    ...)
{
    va_list arglist;
    fprintf(
        stderr, "[%ld](%s:%ld in %s) ", level, file, line, func);
    va_start(arglist, fmt);
    vfprintf(stderr, fmt, arglist);
    va_end(arglist);
    return 0;
}

The code may look complex because of variadic arguments, but it is not. What it does is: first call fprintf to print a prefix (log level, file, line) and then forwards the remaining arguments to vfprintf.

Having this survival_log implemented, I define macros that behave as a regular printf. Under the hoods, they just forward their arguments to survival_log.

DPRINTF for debug messages.
WPRINTF for warning messages.
EPRINTF for error messages.

For example DPRINTF can be defined as:

#define DPRINTF(...)                                                         \
    do {                                                                     \
        survival_log(                                                        \
            SURVIVAL_LOG_DEBUG, __FILE__, __func__, __LINE__, __VA_ARGS__);  \
    } while (0)

You can use those macros as a regular printf. For example:

DPRINTF("checking LIKELY, UNLIKELY\n");
if (LIKELY(rnd > 0)) {
    DPRINTF("rand() is > 0, (%d)\n", rnd);
}

Will produce the following output on stderr:

[debug](survival_demo.c:90 in main) checking LIKELY, UNLIKELY
[debug](survival_demo.c:93 in main) rand() is > 0, (1804289383)

This logging system is a very good start for small projects. Despite its simplicity, I find it very effective in practice. Furthermore, it is very easy to extend if needed (e.g., display timestamps, implement filters, log to files, ...).

Scoped Variables

Again, this topic will be covered in greater details in another post.

When possible I like to use the __cleanup__ attribute available in GCC and Clang. This extension allows to implement automatic cleanup of variables (some sort of RAII in C).

Put shortly, if a variable is marked with this attribute:

__attribute__ ((__cleanup__(int_cleanup))) int x = 42;

Then, the function void int_cleanup(int* ptr) will be called, when variable x goes out of scope. The address of x is passed to int_cleanup as first arguments.

So with attribute, you can automatically release pointers, close files, etc.

However, those annotations quickly make code unreadable. Thus, the first thing to do is to simplify the attribute annotation:

#define SURVIVAL_CLEANUP(func) __attribute__((cleanup(func)))

Basically for each type, I define a scoped_[mytype] macro:

#define scoped_int SURVIVAL_CLEANUP(int_cleanup)

Then, I would create scoped variable with this macros:

// __attribute__ ((__cleanup__(int_cleanup))) int x = 42;
// becomes:
scoped_int int x = 42;

We could also think of a scoped_int macro that would expand to __attribute__ ((__cleanup__(int_cleanup))) int. But I like to keep macro expansion straightforward.

Another annoying aspect of the cleanup extension is in the definition of cleanup handlers.

Let's say you want to automatically close a file. You would be tempted to declare your file as:

__attribute__ ((__cleanup__(fclose))) FILE* f = NULL;

However, fclose does not have the correct prototype, because the cleanup extension will pass the address of f (a FILE** type). To automatically generate wrappers I use the following macro (taken from System-D codebase).

#define DEFINE_TRIVIAL_CLEANUP_FUNC(name, type, func)                          \
    static void name(type* p)                                                  \
    {                                                                          \
        if (*p) {                                                              \
            func(*p);                                                          \
        }                                                                      \
    }                                                                          \
    struct __useless_struct_to_allow_trailing_semicolon__

With this macro, you can define a scoped file as follows:

// Instanciate a trivial cleanup function for FILE* types.
DEFINE_TRIVIAL_CLEANUP_FUNC(
    file_cleanup, /* Name for the wrapper generated. */
    FILE*,        /* Type passed to the destructor. */
    fclose        /* Destructor invoked. */
);

// Attribute to declare scoped files.
#define scoped_file SURVIVAL_CLEANUP(file_cleanup)

// Example scoped file:
scoped_file FILE* f = fopen("foo", "r");

Conclusion

I packed the macro described in this post in a header survival.h. You can see them in action in a small demo here.

I would be interested to hear what are your most useful macros. Feel free to PM me or open an discussion on the Github repository.