Picture

Word allows a picture to be placed in a graphical object container, either an inline shape or a floating shape.

Candidate protocol

>>> run = paragraph.add_run()
>>> inline_shape = run.add_picture(file_like_image, MIME_type=None)
>>> inline_shape.width = width
>>> inline_shape.height = height

Minimal XML

This XML represents the working hypothesis of the minimum XML that must be inserted to add a working picture to a document:

<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
  <pic:nvPicPr>
    <pic:cNvPr id="1" name="python-powered.png"/>
    <pic:cNvPicPr/>
  </pic:nvPicPr>
  <pic:blipFill>
    <a:blip r:embed="rId7"/>
    <a:stretch>
      <a:fillRect/>
    </a:stretch>
  </pic:blipFill>
  <pic:spPr>
    <a:xfrm>
      <a:off x="0" y="0"/>
      <a:ext cx="859536" cy="343814"/>
    </a:xfrm>
    <a:prstGeom prst="rect"/>
  </pic:spPr>
</pic:pic>

Required parameters:

  • unique DrawingML object id (document-wide, pretty sure it’s just the part)
  • name, either filename or generic if file-like object.
  • rId for rel to image part
  • size (cx, cy)

Specimen XML

This XML represents a picture inserted inline on a paragraph by itself:

<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
  <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
    <pic:nvPicPr>
      <pic:cNvPr id="1" name="python-powered.png"/>
      <pic:cNvPicPr/>
    </pic:nvPicPr>
    <pic:blipFill>
      <a:blip r:embed="rId7">
        <a:alphaModFix/>
        <a:extLst>
          <a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}">
            <a14:useLocalDpi xmlns:a14="http://schemas.microsoft.com/office/drawing/2010/main" val="0"/>
          </a:ext>
        </a:extLst>
      </a:blip>
      <a:stretch>
        <a:fillRect/>
      </a:stretch>
    </pic:blipFill>
    <pic:spPr>
      <a:xfrm>
        <a:off x="0" y="0"/>
        <a:ext cx="859536" cy="343814"/>
      </a:xfrm>
      <a:prstGeom prst="rect">
        <a:avLst/>
      </a:prstGeom>
    </pic:spPr>
  </pic:pic>
</a:graphicData>

Schema definitions

<xsd:element name="pic" type="CT_Picture"/>

<xsd:complexType name="CT_Picture">
  <xsd:sequence>
    <xsd:element name="nvPicPr"  type="CT_PictureNonVisual"/>
    <xsd:element name="blipFill" type="a:CT_BlipFillProperties"/>
    <xsd:element name="spPr"     type="a:CT_ShapeProperties"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="CT_PictureNonVisual">
  <xsd:sequence>
    <xsd:element name="cNvPr"    type="a:CT_NonVisualDrawingProps"/>
    <xsd:element name="cNvPicPr" type="a:CT_NonVisualPictureProperties"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="CT_BlipFillProperties">
  <xsd:sequence>
    <xsd:element name="blip"    type="CT_Blip"         minOccurs="0"/>
    <xsd:element name="srcRect" type="CT_RelativeRect" minOccurs="0"/>
    <xsd:choice minOccurs="0">
      <xsd:element name="tile"    type="CT_TileInfoProperties"/>
      <xsd:element name="stretch" type="CT_StretchInfoProperties"/>
    </xsd:choice>
  </xsd:sequence>
  <xsd:attribute name="dpi"          type="xsd:unsignedInt"/>
  <xsd:attribute name="rotWithShape" type="xsd:boolean"/>
</xsd:complexType>

<xsd:complexType name="CT_ShapeProperties">
  <xsd:sequence>
    <xsd:element name="xfrm"    type="CT_Transform2D"            minOccurs="0"/>
    <xsd:group   ref="EG_Geometry"                               minOccurs="0"/>
    <xsd:group   ref="EG_FillProperties"                         minOccurs="0"/>
    <xsd:element name="ln"      type="CT_LineProperties"         minOccurs="0"/>
    <xsd:group   ref="EG_EffectProperties"                       minOccurs="0"/>
    <xsd:element name="scene3d" type="CT_Scene3D"                minOccurs="0"/>
    <xsd:element name="sp3d"    type="CT_Shape3D"                minOccurs="0"/>
    <xsd:element name="extLst"  type="CT_OfficeArtExtensionList" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="bwMode" type="ST_BlackWhiteMode"/>
</xsd:complexType>

<xsd:complexType name="CT_Blip">  <!-- denormalized -->
  <xsd:sequence>
    <xsd:choice minOccurs="0" maxOccurs="unbounded">
      <xsd:element name="alphaBiLevel" type="CT_AlphaBiLevelEffect"/>
      <xsd:element name="alphaCeiling" type="CT_AlphaCeilingEffect"/>
      <xsd:element name="alphaFloor"   type="CT_AlphaFloorEffect"/>
      <xsd:element name="alphaInv"     type="CT_AlphaInverseEffect"/>
      <xsd:element name="alphaMod"     type="CT_AlphaModulateEffect"/>
      <xsd:element name="alphaModFix"  type="CT_AlphaModulateFixedEffect"/>
      <xsd:element name="alphaRepl"    type="CT_AlphaReplaceEffect"/>
      <xsd:element name="biLevel"      type="CT_BiLevelEffect"/>
      <xsd:element name="blur"         type="CT_BlurEffect"/>
      <xsd:element name="clrChange"    type="CT_ColorChangeEffect"/>
      <xsd:element name="clrRepl"      type="CT_ColorReplaceEffect"/>
      <xsd:element name="duotone"      type="CT_DuotoneEffect"/>
      <xsd:element name="fillOverlay"  type="CT_FillOverlayEffect"/>
      <xsd:element name="grayscl"      type="CT_GrayscaleEffect"/>
      <xsd:element name="hsl"          type="CT_HSLEffect"/>
      <xsd:element name="lum"          type="CT_LuminanceEffect"/>
      <xsd:element name="tint"         type="CT_TintEffect"/>
    </xsd:choice>
    <xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute  ref="r:embed" type="ST_RelationshipId"  default=""/>
  <xsd:attribute  ref="r:link"  type="ST_RelationshipId"  default=""/>
  <xsd:attribute name="cstate"  type="ST_BlipCompression" default="none"/>
</xsd:complexType>

<xsd:simpleType name="ST_RelationshipId">
  <xsd:restriction base="xsd:string"/>
</xsd:simpleType>

<xsd:complexType name="CT_NonVisualDrawingProps">
  <xsd:sequence>
    <xsd:element name="hlinkClick" type="CT_Hyperlink"              minOccurs="0"/>
    <xsd:element name="hlinkHover" type="CT_Hyperlink"              minOccurs="0"/>
    <xsd:element name="extLst"     type="CT_OfficeArtExtensionList" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="id"     type="ST_DrawingElementId" use="required"/>
  <xsd:attribute name="name"   type="xsd:string"          use="required"/>
  <xsd:attribute name="descr"  type="xsd:string"          default=""/>
  <xsd:attribute name="hidden" type="xsd:boolean"         default="false"/>
  <xsd:attribute name="title"  type="xsd:string"          default=""/>
</xsd:complexType>

<xsd:complexType name="CT_NonVisualPictureProperties">
  <xsd:sequence>
    <xsd:element name="picLocks" type="CT_PictureLocking"         minOccurs="0"/>
    <xsd:element name="extLst"   type="CT_OfficeArtExtensionList" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="preferRelativeResize" type="xsd:boolean" default="true"/>
</xsd:complexType>

<xsd:complexType name="CT_Point2D">
  <xsd:attribute name="x" type="ST_Coordinate" use="required"/>
  <xsd:attribute name="y" type="ST_Coordinate" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_PositiveSize2D">
  <xsd:attribute name="cx" type="ST_PositiveCoordinate" use="required"/>
  <xsd:attribute name="cy" type="ST_PositiveCoordinate" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_PresetGeometry2D">
  <xsd:sequence>
    <xsd:element name="avLst" type="CT_GeomGuideList" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="prst" type="ST_ShapeType" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_RelativeRect">
  <xsd:attribute name="l" type="ST_Percentage" default="0%"/>
  <xsd:attribute name="t" type="ST_Percentage" default="0%"/>
  <xsd:attribute name="r" type="ST_Percentage" default="0%"/>
  <xsd:attribute name="b" type="ST_Percentage" default="0%"/>
</xsd:complexType>

<xsd:complexType name="CT_StretchInfoProperties">
  <xsd:sequence>
    <xsd:element name="fillRect" type="CT_RelativeRect" minOccurs="0"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="CT_Transform2D">
  <xsd:sequence>
    <xsd:element name="off" type="CT_Point2D"        minOccurs="0"/>
    <xsd:element name="ext" type="CT_PositiveSize2D" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="rot"   type="ST_Angle"    default="0"/>
  <xsd:attribute name="flipH" type="xsd:boolean" default="false"/>
  <xsd:attribute name="flipV" type="xsd:boolean" default="false"/>
</xsd:complexType>

<xsd:group name="EG_FillModeProperties">
  <xsd:choice>
    <xsd:element name="tile"    type="CT_TileInfoProperties"/>
    <xsd:element name="stretch" type="CT_StretchInfoProperties"/>
  </xsd:choice>
</xsd:group>

<xsd:group name="EG_Geometry">
  <xsd:choice>
    <xsd:element name="custGeom" type="CT_CustomGeometry2D"/>
    <xsd:element name="prstGeom" type="CT_PresetGeometry2D"/>
  </xsd:choice>
</xsd:group>