Improved domain referenced objects docs

In particular, added example for layout images, showing how their
position can reference an axis domain.

Author: nicholas-esterer

doc/python/horizontal-vertical-shapes.md

@@ -34,11 +34,16 @@ jupyter:
 
 ### Horizontal and Vertical Lines and Boxes (Autoshapes) in Plotly.py
 
+*introduced in plotly 4.12*
+
 Horizontal and vertical lines and rectangles (autoshapes) that span an entire
 plot can be added via the `add_hline`, `add_vline`, `add_hrect`, and `add_vrect`
-methods of `plotly.graph_objects.Figure`. These shapes are fixed to the
-endpoints of one axis, regardless of the range of the plot, and fixed to data
-coordinates on the other axis. For example
+methods of `plotly.graph_objects.Figure`. Shapes added with these methods are
+added as [layout shapes](/python/shapes) (as shown when doing `print(fig)`, for
+example). These shapes are fixed to the endpoints of one axis, regardless of the
+range of the plot, and fixed to data coordinates on the other axis. The
+following shows some possibilities, try panning and zooming the resulting figure
+to see how the shapes stick to some axes:
 
 
 ```python
@@ -59,7 +64,7 @@ fig.add_vrect(x0=5.5, x1=6.5, line_color="purple")
 # Add a horizontal rectangle that spans the entire x axis
 # intersecting the y axis at 2.5 and 4
 fig.add_hrect(y0=2.5, y1=4, line_color="orange")
-# (try dragging the plot around)
+# (try panning and zooming the plot)
 fig.show()
 ```
 
@@ -88,8 +93,8 @@ example.
 
 #### Adding Text Annotations to Autoshapes
 
-Text can be added to an autoshape using the `annotation` keyword. Using the
-above example:
+Text [annotations](/python/text-and-annotations) can be added to an autoshape
+using the `annotation` keyword. Using the above example:
 ```python
 import plotly.express as px
 import plotly.graph_objects as go

doc/python/images.md

@@ -360,7 +360,41 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
 ```
 
 
-### Images Placed Relative to the Axes
+### Images Placed Relative to Axes
+
+Using `xref='x domain'` or `yref='y domain'`, images can be placed relative to
+axes. As an example, the following shows how to put an image in the top corner
+of a subplot (try panning and zooming the resulting figure):
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", facet_col="species")
+# sources of images
+sources = [
+    "https://upload.wikimedia.org/wikipedia/commons/thumb/f/fe/Iris_setosa_var._setosa_%282595031014%29.jpg/360px-Iris_setosa_var._setosa_%282595031014%29.jpg",
+    "https://upload.wikimedia.org/wikipedia/commons/thumb/3/38/Iris_versicolor_quebec_1.jpg/320px-Iris_versicolor_quebec_1.jpg",
+    "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/Iris_virginica_2.jpg/480px-Iris_virginica_2.jpg",
+]
+# add images
+for col, src in enumerate(sources):
+    fig.add_layout_image(
+        row=1,
+        col=col + 1,
+        source=src,
+        xref="x domain",
+        yref="y domain",
+        x=1,
+        y=1,
+        xanchor="right",
+        yanchor="top",
+        sizex=0.2,
+        sizey=0.2,
+    )
+
+fig.show()
+```
 
 #### Reference
 See https://plotly.com/python/reference/layout/images/ for more information and chart attribute options!