Antas - (from the french word "Entasse")

antas is a cli tool that takes a path to a pdf file as input and render each page into a .png file

the pdf pages are always saved in the path:

{temp_dir}/{input_file_hash}/{when}/page_{id}.png

• temp_dir refers to the the temporary directory on your machine

• input_file_hash is the hash of the given file computed via the sha256 algorithm. so multiple files are grouped.

• when is meant for uniqueness of runs (so threading, goroutines, doesn't create race conditions). when is computed from three values: Now() represented via the Unix representation number, the current PID (Process Id of antas), and a process-wide atomic counter that guarantees no two goroutines ever produce the same path even within the same second.

  TL.DR {when} = {Now().UnixTime}-{pid}-{seq}

• id is simply the number of the page

Usage:

# replace e with the name/path to the antas flavour

<e> <path/to/file.pdf> [options]

Options:
    -f, --format: in what format antas should make it's report [ json | human ] (default "human")
    -h, --help: print this message

when running antas two non-zero exit codes may be returned

1. something went wrong inside of antas (i.e: file not found)
2. you passed an unknown, incorrect flag value (i.e: -f "unknown formatter")

on exit code 2, you'll have to deal with an unstructured string

on exit code 1 (and if using -f json) the error will be returned as so in stdout

{
    "ok": false,
    "error": string
}

if the exit code is 0 and the value json was passed to the -f, --format flag

antas will give you the given payload to parse

{
    "ok": true,
    "out_dir": string,
    "page_count": int
}

Compilation

antas, use go-pdfium to render the pdf page into actual images and other three build favor (2 direct/ 1 indirect)

• classic (webassembly, direct)
• native (CGO required and pdfium setup, direct)
• turbo (use libjpeg-turbo for the rendering system, indirect)

1. classic

this one will use the webassembly version of go-pdfium

command: go build -o antas .

in order to run the webassembly version, go-pdfium will use wazero under the hood, but you won't have to deal with that. this also grants sandboxing out of the box, which may be useful if you have to deal with untrusted pdf files (i.e: users uploading files). and also make cross-compilation easier since it doesn't use CGO.

however it is known to be much slower(2x) than the native version

Warning

The following may and will be a pain in the ass on non-linux based OS to compile and run, especially windows.

2. native

command: go build -tags="natif pdfium_use_turbojpeg" antas-natif .

This one is the fastest but requires a few stuffs installed and configured on your system

• CGO enabled

• a compiled pdfium version for your system

  some precompiled releases are available at https://github.com/bblanchon/pdfium-binaries/releases unless you feel like compiling it yourself.

• pkg-config

the instructions relative setup for it is available at https://github.com/klippa-app/go-pdfium#configure-pkg-config

Make sure you extend your library path when running: export LD_LIBRARY_PATH={path}/lib

I generally recommend not removing the installed libraries as they're still needed at runtime.

one may find convenient to add this at the end of their shell configuration file (i.e: .zshrc, .bashrc, etc...)

export PKG_CONFIG_PATH=/opt/pdfium/lib/pkgconfig
export LD_LIBRARY_PATH=/opt/pdfium/lib

3. turbo

command: go build -tags pdfium_use_turbo_jpeg -o antas-turbo .

this one is apparently supposed to use a faster encoding system via libjpeg-turbo, although most benchmarsk turned out to make him the slowest of the family. i wouldn't recommend using it unless your the benchmark on your machine says otherwise

Sandboxing

in most cases you'll probably want to use antas-natif, if it runs in a dedicated server the docker file will provide a simple way to built a docker image

you can then sandbox antas-natif with control of the system.

Docker

Pre-built images of antas-natif are published to the GitHub Container Registry on every release:

docker pull ghcr.io/ud20-dev/antas:latest

Getting the rendered pages out

antas-natif writes its output to /tmp inside the container — that directory is not your host's /tmp. To get the pages out you need to mount a host directory over /tmp before running:

docker run --rm \
  -v /path/to/your/pdfs:/work \
  -v /path/on/host/output:/tmp \
  ghcr.io/ud20-dev/antas:latest \
  file.pdf

After the container exits the rendered pages will be at /path/on/host/output/{hash}/{when}/page_1.png, etc.

If you want to know the exact output path without guessing the hash, use -f json — antas will print the out_dir to stdout before the container exits:

OUT=$(docker run --rm \
  -v /path/to/your/pdfs:/work \
  -v /path/on/host/output:/tmp \
  ghcr.io/ud20-dev/antas:latest \
  file.pdf -f json)

echo "$OUT"
# {"ok":true,"out_dir":"/tmp/096c84.../{when}","page_count":3}

OUT_DIR=$(echo "$OUT" | grep -o '"out_dir":"[^"]*"' | cut -d'"' -f4)
echo "Pages are at: $OUT_DIR"

Available tags

tag	meaning
latest	most recent release
1.0, 1.0.0	specific version