Drawing image support

[mbway]

This PR adds support for the drawing addon to draw Image entities as requested here

The approach is for the frontend to load the image and apply any effects and clipping paths by altering the pixels of the image (so the image is pre-cropped before it is sent to the backend).

This design allows the backends to be relatively simple: they are given an array containing RGBA pixels (even if the image on disk has no transparency) and a Matrix44 indicating the transform to apply to the image when drawing it.

I have implemented image rendering in Qt and matplotlib and compared to a fairly detailed reference document that a colleague prepared for me.

reference image (created in AutoCAD) ezdxf matplotlib -> pdf render (with white background / paperspace): ezdxf Qt viewer:

So as you can see from the images above, the addon now supports:

• all kinds of transformations including mirroring and transforms from being inside a block
• transparency (images with alpha channel + transparency from entity)
• image effects (brightness, fade, contrast)
• polygon clipping paths
• rendering hidden and missing images

I think the support is pretty good and should cover almost all use cases but there are still some things I'm not sure about:

• the exact algorithm for 'brightness' is unclear
  • the value is 0-100 where 50 means leave unchanged and 100 means pure white
  • the example document did not have any brightness < 50 but I assume it tends towards black so that's what I implemented
  • using PIL.ImageEnhance.Brightness() did not give the expected results when scaling the 0-100 value to 0-2
• the exact algorithm for 'contrast' is unclear
  • the value is 0-100 where 50 means leave unchanged
  • not sure what 'full' contrast would be. I chose to map 0-100 to 0-2 and use PIL.ImageEnhance.Contrast() which looks about right
• the exact algorithm for 'fade' is unclear
  • it seems to blend the image towards the background color (so appears different in the modelspace vs paperspace)
• it's unclear how these effects combine when used together. The only example I have is with them all set to 100 and that appears pure white so I put the brightness adjustment last
• there are some additional attributes in the dxf that aren't covered by my example document so I had to guess
  • I think maybe SHOW_IMAGE_WHEN_NOT_ALIGNED is to do with viewing images in 3D? This flag is currently not used
  • I assume that if USE_CLIPPING_BOUNDARY is not set, act like the clipping path doesn't exist
  • I assume absolute file paths aren't possible. I'm doing a simple conversion from windows-style path separators to the current OS path separators but I don't know if there are any unhandled edge cases
  • I assume that DXFEntity.transparency works as expected when applied to an Image entity

There are some limitations:

• when the image is missing, the filename is displayed centered in the image rectangle. I have only done a minimal implementation of this. The text isn't centered and the font size is fixed
• the performance probably isn't amazing as each effect creates new copies of the image, but it simplifies the logic so I think it's worth it

[mbway]

I missed that new svg and pdf backends have been added that do not use matplotlib. I'll look into those soon.

btw, this PR includes the reference dxf file and the associated images which comes to ~650KiB. Is that OK or would you prefer if I remove them?

[mozman]

@mbway Thanks for your great work!

A future improvement would be to move the clipping of the image to the designer stage, where the viewport clipping happens. This may allow to clip the images at the viewport borders.

[mbway]

I suppose clipping could be moved entirely to the designer, or it could be done twice, so the frontend clips the image to its boundary and the designer clips to the active viewport (if there is one)? but that's up to you