From 7c8cb479f9af2b50ad0d42a3f38dc1a4feb9080b Mon Sep 17 00:00:00 2001
From: Alex Jordan <alex.jordan@pcc.edu>
Date: Sat, 12 Aug 2023 20:16:23 -0700
Subject: [PATCH] vertical alignment for images

---
 htdocs/js/ImageView/imageview.css | 12 ++++++++++++
 macros/core/PGML.pl               | 13 +++++++------
 macros/core/PGbasicmacros.pl      | 21 ++++++++++++++++++---
 t/tikz_test/tikz_image.t          |  2 +-
 4 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/htdocs/js/ImageView/imageview.css b/htdocs/js/ImageView/imageview.css
index 874d9647a8..d8aca9fd9f 100644
--- a/htdocs/js/ImageView/imageview.css
+++ b/htdocs/js/ImageView/imageview.css
@@ -2,6 +2,18 @@
 	cursor: pointer;
 }
 
+.image-view-elt.top {
+	vertical-align: text-top;
+}
+
+.image-view-elt.middle {
+	vertical-align: middle;
+}
+
+.image-view-elt.bottom {
+	vertical-align: baseline;
+}
+
 .image-view-dialog.modal {
 	padding: 0 !important;
 }
diff --git a/macros/core/PGML.pl b/macros/core/PGML.pl
index c1420406ae..e4ccb8c305 100644
--- a/macros/core/PGML.pl
+++ b/macros/core/PGML.pl
@@ -636,7 +636,7 @@ sub NOOP {
 		terminator         => qr/!\]/,
 		terminateMethod    => 'terminateGetString',
 		cancelNL           => 1,
-		options            => [ "source", "width", "height" ]
+		options            => [ "source", "width", "height", "image_options" ]
 	},
 	"[<" => {
 		type               => 'link',
@@ -1362,11 +1362,12 @@ sub Text {
 
 sub Image {
 	my ($self, $item) = @_;
-	my $text   = $item->{text};
-	my $source = $item->{source};
-	my $width  = $item->{width}  || '';
-	my $height = $item->{height} || '';
-	return (main::image($source, alt => $text, width => $width, height => $height));
+	my $text          = $item->{text};
+	my $source        = $item->{source};
+	my $width         = $item->{width}         || '';
+	my $height        = $item->{height}        || '';
+	my $image_options = $item->{image_options} || {};
+	return (main::image($source, alt => $text, width => $width, height => $height, %$image_options));
 }
 
 ######################################################################
diff --git a/macros/core/PGbasicmacros.pl b/macros/core/PGbasicmacros.pl
index 30956f3272..02e9d044d9 100644
--- a/macros/core/PGbasicmacros.pl
+++ b/macros/core/PGbasicmacros.pl
@@ -2940,7 +2940,7 @@ =head2 Macros for displaying images
 
 Usage:
 
-    image($image, width => 200, height => 200, tex_size => 800, alt => 'alt text', extra_html_tags => 'style="border:solid black 1pt"');
+    image($image, width => 200, height => 200, tex_size => 800, valign => 'middle', alt => 'alt text', extra_html_tags => 'style="border:solid black 1pt"');
 
 where C<$image> can be a local file path, URL, WWPlot object, PGlateximage object,
 PGtikz object, or parser::GraphTool object.
@@ -2957,6 +2957,9 @@ =head2 Macros for displaying images
 HTML version with a 600 pixel wide reading area. If C<width> is missing and C<height>
 is declared, we presume this is a wide image and then C<tex_size> defaults to 800.
 
+C<valign> can be 'top', 'middle', or 'bottom'.  This aligns the image relative to
+the surrounding line of text.
+
     image([$image1,$image2], width => 200, height => 200, tex_size => 800, alt => ['alt text 1','alt text 2'], extra_html_tags => 'style="border:solid black 1pt"');
     image([$image1,$image2], width => 200, height => 200, tex_size => 800, alt => 'common alt text', extra_html_tags => 'style="border:solid black 1pt"');
 
@@ -2976,6 +2979,7 @@ sub image {
 		width    => '',
 		height   => '',
 		tex_size => '',
+		valign   => 'middle',
 		# default value for alt is undef, since an empty string is the explicit indicator of a decorative image
 		alt             => undef,
 		extra_html_tags => '',
@@ -3004,6 +3008,9 @@ sub image {
 	my $width_ratio = $tex_size * (.001);
 	my @image_list  = ();
 	my @alt_list    = ();
+	my $valign      = 'middle';
+	$valign = 'top'    if ($out_options{valign} eq 'top');
+	$valign = 'bottom' if ($out_options{valign} eq 'bottom');
 
 	# if width and/or height are explicit, create string for attribute to be used in HTML, LaTeX2HTML
 	my $width_attrib  = ($width)  ? qq{ width="$width"}   : '';
@@ -3046,7 +3053,15 @@ sub image {
 			# We're going to create PDF files with our TeX (using pdflatex), so
 			# alias should have given us the path to a PNG image.
 			if ($imagePath) {
-				$out = "\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}\n";
+				if ($valign eq 'top') {
+					$out =
+						"\\raisebox{-\\height + \\fontcharht\\font`I}{\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}}\n";
+				} elsif ($valign eq 'bottom') {
+					$out = "\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}\n";
+				} else {
+					$out =
+						"\\raisebox{-0.5\\height + 0.5\\fontcharht\\font`I}{\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}}\n";
+				}
 			} else {
 				$out = "";
 			}
@@ -3067,7 +3082,7 @@ sub image {
 			my $altattrib = '';
 			if (defined $alt_list[0]) { $altattrib = 'alt="' . encode_pg_and_html(shift @alt_list) . '"' }
 			$out =
-				qq!<IMG SRC="$imageURL" class="image-view-elt" tabindex="0" role="button"$width_attrib$height_attrib $out_options{extra_html_tags} $altattrib>!;
+				qq!<IMG SRC="$imageURL" class="image-view-elt $valign" tabindex="0" role="button"$width_attrib$height_attrib $out_options{extra_html_tags} $altattrib>!;
 		} elsif ($displayMode eq 'PTX') {
 			my $ptxwidth = ($width ? int($width / 6) : 80);
 			if (defined $alt) {
diff --git a/t/tikz_test/tikz_image.t b/t/tikz_test/tikz_image.t
index bcc0e0e19a..d4c692c96c 100644
--- a/t/tikz_test/tikz_image.t
+++ b/t/tikz_test/tikz_image.t
@@ -28,7 +28,7 @@ ok my $img = image($drawing), 'img tag is generated';
 like $img, qr!
 	^<IMG\s
 	SRC="/pg_files/tmp/images/([a-z0-9_-]*)\.svg"\s
-	class="image-view-elt"\s
+	class="image-view-elt\smiddle"\s
 	tabindex="0"\s
 	role="button"\s
 	width="200"\s*