Images Support

[dolanmiu]

Images Support

[felipeochoa]

Regarding the module organization, I like the idea of making drawing its own top-level. I would also suggest putting more than one element per file when they're tightly coupled

[dolanmiu]

Done! docx now supports images:

https://github.com/dolanmiu/docx/wiki/Images

Will Release in 4.x.x

[dolanmiu]

Work is being done here:

https://github.com/dolanmiu/docx/tree/image-support

Following the following documentation:

https://github.com/dolanmiu/Office-Open-XML-Reference/wiki/DrawingML-Pictures-Overview

https://github.com/dolanmiu/Office-Open-XML-Reference/wiki/Pictures-Image-Properties

[dolanmiu]

@felipeochoa What do you think of this idea:

A Media class, which is like a data store for all the images, and other media etc. It will have addMedia(), and getMedia() methods. It is analogous to the Style and Numbering class. The Media class then gets added into the exporter/packer as a parameter, like the rest.

I say this because whenever you add an image, the image goes into the /media folder in the .docx file.

Then you can do:

const document = new docx.Document();
const media = new docx.Media();

media.addMedia("./my/cool/image.png", "cool-image");

const paragraph = new docx.Paragraph();
paragraph.addPictureRun(media.getMedia("cool-image"));

document.addParagraph(paragraph);

What do you think? Got any other suggestions?

I think this would be cool:

paragraph.addPicture("./my/cool/image.png");

But I do not think its possible with the way Word works with the whole rId5 and media folder and all.

[felipeochoa]

I just looked over the references you linked, and I like the approach. What would this look like when packing? If I understand correctly, it looks like there are three things that need to happen:

1. The <pic/> element is inserted in the <w:body> somewhere
2. The basic picture information needs to be stored somewhere. I guess this is like the styles top-level file?
3. The picture binary data needs to be added to the media folder

The first point is taken care of by paragraph.addPictureRun and is straightforward. The second two are where I think you'll need support from the packer. In order to keep things simple and flexible, would it be better to have addMedia accept a readable stream, a filename, and a media ID instead of filename and ID? So you would do:

media.addMedia(fs.createReadableStream("./my/cool/image.png"), "cool-image", "cool-image.png");

That way if users have non file-system images, they can add them easily. It also enables users to specify a different in-archive name. The third argument could even be optional and default to a random 16-character word. Archiver's .append accepts streams, so it would be straightforward to implement the 2nd and 3rd points.

[felipeochoa]

Also, a couple of small consistency points:

• What other types of media are there? Is there a reason to call the class Media rather than Pictures?
• I think as it looks now, it should be createMedia not addMedia

[dolanmiu]

1. <pic> is added inside <graphic>, which is inside <drawing>, which is inside a <run>
2. I do not think picture information is stored in the styles, its stored inside the <graphic> mentioned above
3. Yes, the actual binary file is inside the media folder

I want paragraph to have a universal addRun, which supports both TextRun and PictureRun

Yes I agree createMedia will make the API more consistent

and yes, createMedia should take file-path as well as readable stream, perhaps an overloaded function

Whoops! I got mixed up, yes there is only one type of media (I believe), which is picture, but there are multiple types of drawing:

• Pictures
• Shapes
• Diagrams
• Textboxes

Reference: https://github.com/dolanmiu/Office-Open-XML-Reference/wiki/DrawingML-Overview

[dolanmiu]

perhaps createMedia should now be called createPicture

[felipeochoa]

Oh ok got it. I like createPicture and the overall approach!

[dolanmiu]

Hey @felipeochoa, could you lend a hand? I have you most of the images working, but when I try to create it, it gives a blank picture with an error. I am not sure whats wrong or whats causing this.

Could you take a look. Screenshot is attached:

Everything is on the image-support branch

[felipeochoa]

@dolanmiu I was looking through the code, but there's a lot going on. How do I reproduce the file you in the screenshot? Can you give me a quick overview of the code you've written for this?

[dolanmiu]

To reproduce, simply:

npm run demo

In the command line

p.s. I have invited you as a collaborator on the project :D

[felipeochoa]

Thanks for adding me! I'll continue to send PRs to give you a chance to weigh in on the code if you want 😄

Regarding the images, here are some small issues I discovered:

• The pic:pic element isn't setting the xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" attritbue, which it should so that the XML reader can interpret all the pic: namespaces.
• The wp:inline element must have docPr and extent children
• The a:graphicData element requires a uri attribute. (LibreOffice sets it to "http://schemas.openxmlformats.org/drawingml/2006/picture")
• pic:pic must have nvPicPr and spPr children

Unfortunately, fixing those issues is not enough to get the picture to display. I still don't have a great understanding of how the picture embedding works, so not sure I can be of much more use right now. Maybe these comments are enough to get you unstuck.

As a side note, splitting the code across so many files and directories makes it challenging to understand what is going on. Especially ts/docx/run/run-components/drawing/ with its deeply nested directories was tough.

[dolanmiu]

That would be nice 😂

on the image-support branch, I have done all those things! On master, its outdated.

This is the following result:

<w:drawing>
    <wp:inline distT="0" distB="0" distL="0" distR="0">
        <wp:extent cx="3947160" cy="3947160"></wp:extent>
        <wp:effectExtent l="0" t="0" r="0" b="0"></wp:effectExtent>
        <wp:docPr id="1" name="Picture 1" desc="cats.jpeg"></wp:docPr>
        <wp:cNvGraphicFramePr>
            <a:graphicFrameLocks
                xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" noChangeAspect="1">
            </a:graphicFrameLocks>
        </wp:cNvGraphicFramePr>
        <a:graphic
            xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
            <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="0" name="Picture 1"></pic:cNvPr>
                        <pic:cNvPicPr>
                            <a:picLocks noChangeAspect="1" noChangeArrowheads="1"></a:picLocks>
                        </pic:cNvPicPr>
                    </pic:nvPicPr>
                    <pic:blipFill>
                        <a:blip r:embed="rId6"></a:blip>
                        <a:srcRect></a:srcRect>
                        <a:stretch>
                            <a:fillRect></a:fillRect>
                        </a:stretch>
                    </pic:blipFill>
                    <pic:spPr bwMode="auto">
                        <a:xfrm>
                            <a:off x="0" y="0"></a:off>
                            <a:ext cx="3947160" cy="3947160"></a:ext>
                        </a:xfrm>
                        <a:prstGeom prst="rect">
                            <a:avLst></a:avLst>
                        </a:prstGeom>
                        <a:noFill></a:noFill>
                        <a:ln>
                            <a:noFill></a:noFill>
                        </a:ln>
                    </pic:spPr>
                </pic:pic>
            </a:graphicData>
        </a:graphic>
    </wp:inline>
</w:drawing>

Yes, I agree, it is quite tough to understand. But I thought that is better than having it all in one single folder. I am thinking of having drawing as a whole new root folder, the same level as docx, because in the Open Office XML Documentation, drawing is cross-app. By that I mean, drawing works with docx, xlsx, pptx etc.

I will write unit tests after an image appears on screen, because all this is experimental and broken. Hope that is ok!

[felipeochoa]

Oh oops. Didn't see that. I created a test document in LibreOffice and then manually modified to mimick this structure, and it works just fine. One thing that struck me is the use of id 0 in cNvPr, but that didn't break the LO document. Also, instead of desc cNvPr should have descr, but that didn't break the document either.
This is the document I made, in case it's useful to compare.

[maugenst]

Hi there.
Are there any plans of merging image-support into master? Or is this a bit stuck?
Thanks and BR

[dolanmiu]

It's a bit stuck, image support branch isnt completed yet

Feel free to make a PR! 😄