feat: support customizable alignment for image display

yazi-adapter/src/adapter.rs

@@ -5,7 +5,7 @@ use ratatui::layout::Rect;
 use tracing::warn;
 use yazi_shared::env_exists;
 
-use crate::{Brand, Emulator, SHOWN, TMUX, WSL, drivers};
+use crate::{Brand, Emulator, Offset, SHOWN, TMUX, WSL, drivers};
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum Adapter {
@@ -35,18 +35,18 @@ impl Display for Adapter {
 }
 
 impl Adapter {
-	pub async fn image_show(self, path: &Path, max: Rect) -> Result<Rect> {
+	pub async fn image_show(self, path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		if max.is_empty() {
 			return Ok(Rect::default());
 		}
 
 		match self {
-			Self::Kgp => drivers::Kgp::image_show(path, max).await,
+			Self::Kgp => drivers::Kgp::image_show(path, max, offset).await,
-			Self::KgpOld => drivers::KgpOld::image_show(path, max).await,
+			Self::KgpOld => drivers::KgpOld::image_show(path, max, offset).await,
-			Self::Iip => drivers::Iip::image_show(path, max).await,
+			Self::Iip => drivers::Iip::image_show(path, max, offset).await,
-			Self::Sixel => drivers::Sixel::image_show(path, max).await,
+			Self::Sixel => drivers::Sixel::image_show(path, max, offset).await,
-			Self::X11 | Self::Wayland => drivers::Ueberzug::image_show(path, max).await,
+			Self::X11 | Self::Wayland => drivers::Ueberzug::image_show(path, max, offset).await,
-			Self::Chafa => drivers::Chafa::image_show(path, max).await,
+			Self::Chafa => drivers::Chafa::image_show(path, max, offset).await,
 		}
 	}
 

yazi-adapter/src/drivers/chafa.rs

@@ -3,15 +3,15 @@ use std::{io::Write, path::Path, process::Stdio};
 use ansi_to_tui::IntoText;
 use anyhow::{Result, bail};
 use crossterm::{cursor::MoveTo, queue};
-use ratatui::layout::Rect;
+use ratatui::layout::{Rect, Size};
 use tokio::process::Command;
 
-use crate::{Adapter, Emulator};
+use crate::{Adapter, Emulator, Offset};
 
 pub(crate) struct Chafa;
 
 impl Chafa {
-	pub(crate) async fn image_show(path: &Path, max: Rect) -> Result<Rect> {
+	pub(crate) async fn image_show(path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		let child = Command::new("chafa")
 			.args([
 				"-f",
@@ -46,11 +46,13 @@ impl Chafa {
 			bail!("failed to parse chafa output");
 		};
 
-		let area = Rect {
+		let area = {
-			x:      max.x,
+			let width = first.width() as u16;
-			y:      max.y,
+			let height = lines.len() as u16;
-			width:  first.width() as u16,
+			let offset = offset.unwrap_or_else(|| {
-			height: lines.len() as u16,
+				Offset::from((Size { width, height }, Size { width: max.width, height: max.height }))
+			});
+			Rect { x: max.x + offset.x, y: max.y + offset.y, width, height }
 		};
 
 		Adapter::Chafa.image_hide()?;

yazi-adapter/src/drivers/iip.rs

@@ -7,14 +7,14 @@ use image::{DynamicImage, ExtendedColorType, ImageEncoder, codecs::{jpeg::JpegEn
 use ratatui::layout::Rect;
 use yazi_config::PREVIEW;
 
-use crate::{CLOSE, Emulator, Image, START, adapter::Adapter};
+use crate::{CLOSE, Emulator, Image, Offset, START, adapter::Adapter};
 
 pub(crate) struct Iip;
 
 impl Iip {
-	pub(crate) async fn image_show(path: &Path, max: Rect) -> Result<Rect> {
+	pub(crate) async fn image_show(path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		let img = Image::downscale(path, max).await?;
-		let area = Image::pixel_area((img.width(), img.height()), max);
+		let area = Image::pixel_area((img.width(), img.height()), max, offset);
 		let b = Self::encode(img).await?;
 
 		Adapter::Iip.image_hide()?;

yazi-adapter/src/drivers/kgp.rs

@@ -7,7 +7,7 @@ use crossterm::{cursor::MoveTo, queue};
 use image::DynamicImage;
 use ratatui::layout::Rect;
 
-use crate::{CLOSE, ESCAPE, Emulator, START, adapter::Adapter, image::Image};
+use crate::{CLOSE, ESCAPE, Emulator, Offset, START, adapter::Adapter, image::Image};
 
 static DIACRITICS: [char; 297] = [
 	'\u{0305}',
@@ -312,9 +312,9 @@ static DIACRITICS: [char; 297] = [
 pub(crate) struct Kgp;
 
 impl Kgp {
-	pub(crate) async fn image_show(path: &Path, max: Rect) -> Result<Rect> {
+	pub(crate) async fn image_show(path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		let img = Image::downscale(path, max).await?;
-		let area = Image::pixel_area((img.width(), img.height()), max);
+		let area = Image::pixel_area((img.width(), img.height()), max, offset);
 
 		let b1 = Self::encode(img).await?;
 		let b2 = Self::place(&area)?;

yazi-adapter/src/drivers/kgp_old.rs

@@ -6,14 +6,14 @@ use base64::{Engine, engine::general_purpose};
 use image::DynamicImage;
 use ratatui::layout::Rect;
 
-use crate::{CLOSE, ESCAPE, Emulator, Image, START, adapter::Adapter};
+use crate::{CLOSE, ESCAPE, Emulator, Image, Offset, START, adapter::Adapter};
 
 pub(crate) struct KgpOld;
 
 impl KgpOld {
-	pub(crate) async fn image_show(path: &Path, max: Rect) -> Result<Rect> {
+	pub(crate) async fn image_show(path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		let img = Image::downscale(path, max).await?;
-		let area = Image::pixel_area((img.width(), img.height()), max);
+		let area = Image::pixel_area((img.width(), img.height()), max, offset);
 		let b = Self::encode(img).await?;
 
 		Adapter::KgpOld.image_hide()?;

yazi-adapter/src/drivers/sixel.rs

@@ -7,14 +7,14 @@ use image::DynamicImage;
 use ratatui::layout::Rect;
 use yazi_config::PREVIEW;
 
-use crate::{CLOSE, ESCAPE, Emulator, Image, START, adapter::Adapter};
+use crate::{CLOSE, ESCAPE, Emulator, Image, Offset, START, adapter::Adapter};
 
 pub(crate) struct Sixel;
 
 impl Sixel {
-	pub(crate) async fn image_show(path: &Path, max: Rect) -> Result<Rect> {
+	pub(crate) async fn image_show(path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		let img = Image::downscale(path, max).await?;
-		let area = Image::pixel_area((img.width(), img.height()), max);
+		let area = Image::pixel_area((img.width(), img.height()), max, offset);
 		let b = Self::encode(img).await?;
 
 		Adapter::Sixel.image_hide()?;

yazi-adapter/src/drivers/ueberzug.rs

@@ -1,13 +1,13 @@
 use std::{path::{Path, PathBuf}, process::Stdio};
 
 use anyhow::{Result, bail};
-use ratatui::layout::Rect;
+use ratatui::layout::{Rect, Size};
 use tokio::{io::AsyncWriteExt, process::{Child, Command}, sync::mpsc::{self, UnboundedSender}};
 use tracing::{debug, warn};
 use yazi_config::PREVIEW;
 use yazi_shared::{RoCell, env_exists};
 
-use crate::{Adapter, Dimension};
+use crate::{Adapter, Dimension, Offset};
 
 type Cmd = Option<(PathBuf, Rect)>;
 
@@ -41,7 +41,7 @@ impl Ueberzug {
 		DEMON.init(Some(tx))
 	}
 
-	pub(crate) async fn image_show(path: &Path, max: Rect) -> Result<Rect> {
+	pub(crate) async fn image_show(path: &Path, max: Rect, offset: Option<Offset>) -> Result<Rect> {
 		let Some(tx) = &*DEMON else {
 			bail!("uninitialized ueberzugpp");
 		};
@@ -50,11 +50,13 @@ impl Ueberzug {
 		let (w, h) = tokio::task::spawn_blocking(move || image::image_dimensions(p)).await??;
 
 		let area = Dimension::ratio()
-			.map(|(r1, r2)| Rect {
+			.map(|(r1, r2)| {
-				x:      max.x,
+				let width = max.width.min((w.min(PREVIEW.max_width as _) as f64 / r1).ceil() as _);
-				y:      max.y,
+				let height = max.height.min((h.min(PREVIEW.max_height as _) as f64 / r2).ceil() as _);
-				width:  max.width.min((w.min(PREVIEW.max_width as _) as f64 / r1).ceil() as _),
+				let offset = offset.unwrap_or_else(|| {
-				height: max.height.min((h.min(PREVIEW.max_height as _) as f64 / r2).ceil() as _),
+					Offset::from((Size { width, height }, Size { width: max.width, height: max.height }))
+				});
+				Rect { x: max.x + offset.x, y: max.y + offset.y, width, height }
 			})
 			.unwrap_or(max);
 

yazi-adapter/src/image.rs

@@ -2,10 +2,10 @@ use std::path::{Path, PathBuf};
 
 use anyhow::Result;
 use image::{DynamicImage, ExtendedColorType, ImageDecoder, ImageEncoder, ImageError, ImageReader, ImageResult, Limits, codecs::{jpeg::JpegEncoder, png::PngEncoder}, imageops::FilterType, metadata::Orientation};
-use ratatui::layout::Rect;
+use ratatui::layout::{Rect, Size};
 use yazi_config::{PREVIEW, TASKS};
 
-use crate::Dimension;
+use crate::{Dimension, Offset};
 
 pub struct Image;
 
@@ -73,13 +73,15 @@ impl Image {
 			.unwrap_or((PREVIEW.max_width, PREVIEW.max_height))
 	}
 
-	pub(super) fn pixel_area(size: (u32, u32), rect: Rect) -> Rect {
+	pub(super) fn pixel_area(size: (u32, u32), rect: Rect, offset: Option<Offset>) -> Rect {
 		Dimension::ratio()
-			.map(|(r1, r2)| Rect {
+			.map(|(r1, r2)| {
-				x:      rect.x,
+				let width = (size.0 as f64 / r1).ceil() as u16;
-				y:      rect.y,
+				let height = (size.1 as f64 / r2).ceil() as u16;
-				width:  (size.0 as f64 / r1).ceil() as u16,
+				let offset = offset.unwrap_or_else(|| {
-				height: (size.1 as f64 / r2).ceil() as u16,
+					Offset::from((Size { width, height }, Size { width: rect.width, height: rect.height }))
+				});
+				Rect { x: rect.x + offset.x, y: rect.y + offset.y, width, height }
 			})
 			.unwrap_or(rect)
 	}

yazi-adapter/src/lib.rs

@@ -2,7 +2,7 @@
 
 yazi_macro::mod_pub!(drivers);
 
-yazi_macro::mod_flat!(adapter brand dimension emulator image info mux unknown);
+yazi_macro::mod_flat!(adapter brand dimension emulator image info mux offset unknown);
 
 use yazi_shared::{RoCell, SyncCell, env_exists, in_wsl};
 

yazi-adapter/src/offset.rs

@@ -0,0 +1,26 @@
+use ratatui::layout::Size;
+use yazi_config::{PREVIEW, preview::{HorizontalAlignment, VerticalAlignment}};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct Offset {
+	pub x: u16,
+	pub y: u16,
+}
+
+impl From<(Size, Size)> for Offset {
+	fn from(value: (Size, Size)) -> Self {
+		let inner = value.0;
+		let outer = value.1;
+		let offset_x = match PREVIEW.alignment.horizontal {
+			HorizontalAlignment::Left => 0,
+			HorizontalAlignment::Center => (outer.width - inner.width) / 2,
+			HorizontalAlignment::Right => outer.width - inner.width,
+		};
+		let offset_y = match PREVIEW.alignment.vertical {
+			VerticalAlignment::Top => 0,
+			VerticalAlignment::Center => (outer.height - inner.height) / 2,
+			VerticalAlignment::Bottom => outer.height - inner.height,
+		};
+		Self { x: offset_x, y: offset_y }
+	}
+}

yazi-config/preset/yazi-default.toml

@@ -21,6 +21,7 @@ wrap            = "no"
 tab_size = 2
 max_width = 600
 max_height = 900
+alignment = { horizontal = "center", vertical = "top" }
 cache_dir = ""
 image_delay = 30
 image_filter = "triangle"

yazi-config/src/preview/alignment.rs

@@ -0,0 +1,27 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HorizontalAlignment {
+	Left,
+	#[default]
+	Center,
+	Right,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum VerticalAlignment {
+	#[default]
+	Top,
+	Center,
+	Bottom,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct Alignment {
+	#[serde(default)]
+	pub horizontal: HorizontalAlignment,
+	#[serde(default)]
+	pub vertical:   VerticalAlignment,
+}

yazi-config/src/preview/mod.rs

@@ -1 +1 @@
-yazi_macro::mod_flat!(preview wrap);
+yazi_macro::mod_flat!(alignment preview wrap);

yazi-config/src/preview/preview.rs

@@ -6,7 +6,7 @@ use validator::Validate;
 use yazi_fs::{Xdg, expand_path};
 use yazi_shared::timestamp_us;
 
-use super::PreviewWrap;
+use super::{Alignment, PreviewWrap};
 
 #[rustfmt::skip]
 const TABS: &[&str] = &["", " ", "  ", "   ", "    ", "     ", "      ", "       ", "        ", "         ", "          ", "           ", "            ", "             ", "              ", "               ", "                "];
@@ -17,6 +17,7 @@ pub struct Preview {
 	pub tab_size:   u8,
 	pub max_width:  u32,
 	pub max_height: u32,
+	pub alignment:  Alignment,
 
 	pub cache_dir: PathBuf,
 
@@ -72,6 +73,8 @@ impl<'de> Deserialize<'de> for Preview {
 			tab_size:   u8,
 			max_width:  u32,
 			max_height: u32,
+			#[serde(default)]
+			alignment:  Alignment,
 
 			cache_dir: Option<String>,
 
@@ -95,6 +98,7 @@ impl<'de> Deserialize<'de> for Preview {
 			tab_size:   preview.tab_size,
 			max_width:  preview.max_width,
 			max_height: preview.max_height,
+			alignment:  preview.alignment,
 
 			cache_dir: preview
 				.cache_dir

yazi-plugin/src/utils/image.rs

@@ -1,5 +1,5 @@
-use mlua::{Function, IntoLua, Lua, Value};
+use mlua::{Function, IntoLua, Lua, Table, Value};
-use yazi_adapter::{ADAPTOR, Image};
+use yazi_adapter::{ADAPTOR, Image, Offset};
 
 use super::Utils;
 use crate::{bindings::ImageInfo, elements::Rect, url::UrlRef};
@@ -16,13 +16,19 @@ impl Utils {
 	}
 
 	pub(super) fn image_show(lua: &Lua) -> mlua::Result<Function> {
-		lua.create_async_function(|lua, (url, rect): (UrlRef, Rect)| async move {
+		lua.create_async_function(
-			if let Ok(area) = ADAPTOR.image_show(&url, *rect).await {
+			|lua, (url, rect, offset_table): (UrlRef, Rect, Option<Table>)| async move {
+				let offset = offset_table.map(|lua_offset| Offset {
+					x: lua_offset.get("x").unwrap_or(0),
+					y: lua_offset.get("y").unwrap_or(0),
+				});
+				if let Ok(area) = ADAPTOR.image_show(&url, *rect, offset).await {
 					Rect::from(area).into_lua(&lua)
 				} else {
 					Value::Nil.into_lua(&lua)
 				}
-		})
+			},
+		)
 	}
 
 	pub(super) fn image_precache(lua: &Lua) -> mlua::Result<Function> {