Tutorial 2: Basic Interactive Apps (Building an Image Gallery)

In this tutorial, we’ll create our first Meerkat GUI by building an image gallery.

Through this tutorial, you will learn about:

• downloading a dataset

• starting a Meerkat interactive server

• building a layout with components

• launching an app

If you want to follow along, you can run the tutorial demo script.

mk demo tutorial-image-gallery

As always, the first step is to import meerkat! This will give you access to the Meerkat DataFrame object as well as the Meerkat frontend components that will serve as the building blocks for our layouts.

import meerkat as mk

💾 Downloading the dataset

Meerkat provides an interface into many datasets out of the box, but you are always free to download and use any dataset you like, or even make your own dataset.

For this demo, we’re going to use the Imagenette dataset, a small subset of the original ImageNet. This dataset is made up of 10 classes (e.g., “garbage truck”, “gas pump”, “golf ball”). This particular dataset offers three versions, so we’ll choose the smallest by specifying version="160px".

• Download time: <1 minute

• Download size: 206MB

Loading in this dataset will be lightning fast in the future, since Meerkat will cache the data locally.

df = mk.get("imagenette", version="160px")

🕸️ Starting a Meerkat interactive server

Now that we have our dataset, we can spin up a Meerkat interactive server. This will allow us to view our dataset in the browser. By default, the interactive server will run on port 5000, but you can specify a different port if you’d like.

mk.gui.start(api_port=3000)

🖼️ Building the layout

Let’s create our frontend components. Meerkat has numerous components for use out of the box, so we’ll use the Gallery component to display our df DataFrame. You can browse the complete list of components here. We’ll specify the name of the column in our df where our images are stored, and we can optionally specify the names of a few columns to render as tags below each image.

gallery = mk.gui.Gallery(df=df, main_column="img", tag_columns=["path", "label"])

For the final step, we’ll stick our gallery into a Page component, specifying an id of "gallery". Every Meerkat app must have a Page component as its root. The id is used to uniquely identify the page, and the Page is the only comment with the special launch() method.

page = mk.gui.Page(component=gallery, id="gallery")
page.launch()

🚀 Launching the app

Here is all six lines of code put together:

import meerkat as mk


df = mk.get("imagenette", version="160px")
mk.gui.start(api_port=3000)

gallery = mk.gui.Gallery(df=df, main_column="img", tag_columns=["path", "label"])

page = mk.gui.Page(component=gallery, id="gallery")
page.launch()

That’s it! You can run this code either in a standalone .py file or directly in a Jupyter notebook. If running a .py file, use the command mk run <file>.py --dev and follow the link in the terminal to view your app in the browser. Any changes you make to the code will cause the page to automatically refresh. If running in a Jupyter notebook, the app should show up in the cell’s output.

🥳 Congratulations on building your first Meerkat GUI.