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>