Jupyter Integration

After loading the notebook extension with

%load_ext flottplot

Flottplot cells can be created with a %%flottplot magic command. Flottplot elements added to the cell body will be converted when executing the cell. Each Flottplot cell is independent and elements cannot interact between them.

Note that all images must be reachable from the root directory of the notebook server. Because JupyterLab does not serve images directly via URL, the extension does not work properly with the lab interface at the moment.

Command Line Interface

Convenient Flottplot management from the command line:

python3 -m flottplot SUBCOMMAND ARGS...

init

usage: flottplot init [-h] [-e EXT] [-a DIR] [-o] [--no-style] [--no-scan]
                      FILE

Create a new Flottplot page.

positional arguments:
  FILE                  File name for the new Flottplot page. The file
                        extension ".html" is added automatically unless
                        otherwise specfied with -e.

options:
  -h, --help            show this help message and exit
  -e EXT, --extension EXT
                        File extension added to the output page name if not
                        specified by the user already. Set to ".html" by
                        default. If you do not want the file name of the new
                        page to be modified, set this argument to an empty
                        string.
  -a DIR, --asset-dir DIR
                        Output directory for JavaScript and CSS assets,
                        relative to the current directory. The directory will
                        be created if it does not exist. By default, all
                        assets are put into the same directory as the created
                        Flottplot page file.
  -o, --overwrite       Allow overwriting of existing files.
  --no-style            Do not include the Flottplot styling (CSS file) in the
                        output page.
  --no-scan             Do not include the automatic element scan in the
                        output page.

replace

usage: flottplot replace [-h]

Replace Flottplot files (JavaScript, CSS) in the current directory, e.g. to
upgrade to a new version or repair corrupted files.

options:
  -h, --help  show this help message and exit

Access via SSH

Your plots might be saved on a remote machine that you only have SSH access to. In this case instead of transferring all plots to your local machine, you can start a simple web server on the remote machine and use port forwarding to access your flottplot page in your local browser. Many machines have Python 3 installed nowadays, so we can e.g. use the http.simple server. By default, http.simple serves content on port 8000. When connecting with SSH, specify that port 8000 on the local machine should be forwarded to port 8000 on the remote machine:

ssh -L localhost:8000:localhost:8000 user@remote

If you are using a config file for your SSH connections, you can permanently specify the -L option with

LocalForward localhost:8000 localhost:8000

there. When the connection is established, start the webserver with

python3 -m http.server

on the remote machine. It will tell you which port it is serving on. This port must match the one just specified in the SSH command. As long as the SSH connection is open, you can type

http://localhost:8000

into your (local) browser's address bar to access the webserver started on the remote machine. The server will show you the content of the directory that it was started in and if there is a file named index.html it will serve this file immediately (you can also access other files by navigating with the URL in the browser). The server only has access to files inside that directory and its subdirectories, so if you want to access something that is saved in directory ~/aaa, you should start the server in either ~ or ~/aaa, but not ~/bbb. This not just applies to your flottplot page but also all the plots that you include in your flottplot. Make sure you are using relative paths to reference files and employ softlinks to access remote locations you don't have a relative path to.

The server can be stopped with Ctrl-C when you are done.