{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# `geom_imshow()` and `geom_raster()`\n",
"\n",
"`geom_imshow()` displays an image specified by 2D or 3D Numpy array.\n",
"\n",
"Whether the image is grayscale or color depends on the shape of the image array:\n",
"- (M, N) - grey-scale image\n",
"- (M, N, 3) - color RGB image\n",
"- (M, N, 4) - color RGB image with alpha channel\n",
"\n",
"For example, you can create an RGB image array from a PNG file using `PIL` and `io` packages.\n",
"\n",
"`geom_raster()` on the other hand is a regular `ggplot` graphic layer wich takes a data-frame as the input \n",
"and applies the aesthetic mappings as specified by the `aes()` function."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:47.480017Z",
"iopub.status.busy": "2026-01-27T17:08:47.479934Z",
"iopub.status.idle": "2026-01-27T17:08:47.482916Z",
"shell.execute_reply": "2026-01-27T17:08:47.482626Z"
}
},
"outputs": [],
"source": [
"import numpy as np\n",
"import pandas as pd\n",
"\n",
"from lets_plot import *"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:47.484051Z",
"iopub.status.busy": "2026-01-27T17:08:47.483983Z",
"iopub.status.idle": "2026-01-27T17:08:47.485843Z",
"shell.execute_reply": "2026-01-27T17:08:47.485555Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
" \n",
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"LetsPlot.setup_html()"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:47.498907Z",
"iopub.status.busy": "2026-01-27T17:08:47.498823Z",
"iopub.status.idle": "2026-01-27T17:08:48.089539Z",
"shell.execute_reply": "2026-01-27T17:08:48.089088Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"(225, 225, 3)"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from PIL import Image\n",
"import requests\n",
"from io import BytesIO\n",
"\n",
"response = requests.get('https://github.com/JetBrains/lets-plot-docs/raw/master/source/examples/cookbook/images/fisher_boat.png')\n",
"\n",
"image = Image.open(BytesIO(response.content))\n",
"img = np.asarray(image)\n",
"img.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### RGB image\n",
"\n",
"M x N x 3 `ndarray` specifies a color RGB image."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:48.090834Z",
"iopub.status.busy": "2026-01-27T17:08:48.090701Z",
"iopub.status.idle": "2026-01-27T17:08:48.158214Z",
"shell.execute_reply": "2026-01-27T17:08:48.157782Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ggplot() + geom_imshow(img)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Grayscale image\n",
"\n",
"M x N `ndarray` specifies a grayscale image.\n",
"\n",
"We will generate a grayscale image from RGB image above\n",
"by selecting only its `R` channel."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:48.159230Z",
"iopub.status.busy": "2026-01-27T17:08:48.159124Z",
"iopub.status.idle": "2026-01-27T17:08:48.161242Z",
"shell.execute_reply": "2026-01-27T17:08:48.160966Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"(225, 225)"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"img_gs = img[:,:,0]\n",
"img_gs.shape"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:48.162222Z",
"iopub.status.busy": "2026-01-27T17:08:48.162150Z",
"iopub.status.idle": "2026-01-27T17:08:48.181278Z",
"shell.execute_reply": "2026-01-27T17:08:48.180959Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ggplot() + geom_imshow(img_gs)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Grayscale image in pseudo colors (cmap)"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:48.182036Z",
"iopub.status.busy": "2026-01-27T17:08:48.181961Z",
"iopub.status.idle": "2026-01-27T17:08:48.193399Z",
"shell.execute_reply": "2026-01-27T17:08:48.193120Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ggplot() + geom_imshow(img_gs, cmap=\"magma\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### `geom_raster()`\n",
"\n",
"The `geom_raster()` function also can display image. But unlike `geom_imshow()`, `geom_raster()` doesn't accept `ndarray` as an input.\n",
"\n",
"As a regular `ggplot` graphic layer, `geom_raster()` requires an observations-style input data and aestetic mapping.\n",
"\n",
"This is not very convenient when the data is originally in the form of `ndarray`. On the other hand, aesthetic mapping and color scales might come in handy when rendering an image.\n",
"\n",
"Lets transform the image data to a data-frame suitable for `geom_raster()`."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:48.194370Z",
"iopub.status.busy": "2026-01-27T17:08:48.194297Z",
"iopub.status.idle": "2026-01-27T17:08:48.381125Z",
"shell.execute_reply": "2026-01-27T17:08:48.380828Z"
}
},
"outputs": [],
"source": [
"# reshape 3-dimentional ndarray to 2-dimentional long-form ndarray\n",
"# and then to data frame with columns x,y,r,g,b\n",
"cols, rows, _ = img.shape\n",
"img_lf = img.reshape(cols * rows, -1)\n",
"img_df = pd.DataFrame(img_lf,columns=['r','g','b'])\n",
"X_mesh, Y_mesh = np.meshgrid(np.arange(rows), np.arange(cols))\n",
"img_df['x'] = X_mesh.reshape(-1)\n",
"img_df['y'] = Y_mesh.reshape(-1)[::-1]\n",
"\n",
"# Pack color components values to 24-bit RGB values \n",
"c_fill = img_df.apply(lambda row: ((int(row['r'] * 255) << 16) + \n",
" (int(row['g'] * 255) << 8) +\n",
" int(row['b'] * 255)),\n",
" axis=1)"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:48.382330Z",
"iopub.status.busy": "2026-01-27T17:08:48.382237Z",
"iopub.status.idle": "2026-01-27T17:08:48.698579Z",
"shell.execute_reply": "2026-01-27T17:08:48.698239Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Show image in pseudo colors with only few gradations \n",
"(ggplot(img_df) + geom_raster(aes('x', 'y', fill=c_fill), show_legend=False)\n",
" + scale_fill_brewer()\n",
" + ggtitle('Raster geom with brewer palette') + ggsize(800,500))"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.13"
}
},
"nbformat": 4,
"nbformat_minor": 4
}