chore(doc): add new functions to readme

Author: singerla

README.md

@@ -268,6 +268,22 @@ pres.addSlide('RootTemplate.pptx', 1, (slide) => {
     /* ... */
   ]);
 });
+
+// In case you have two or more shapes on your template slide with the same name,
+// you can address the target by nameIdx:
+pres.addSlide('SlideWithGraph.pptx', 1, (slide) => {
+  // Starting from 0, this will find the second shape named 'ColumnChart'
+  // on the slide.
+  slide.modifyElement(
+    {
+      name: 'ColumnChart',
+      nameIdx: 1,
+    },
+    [
+      /* ... */
+    ],
+  );
+});
 ```
 
 > You can display and manage shape names directly in PowerPoint by opening the "Selection"-pane for your current slide. Hit `ALT+F10` and PowerPoint will give you a (nested) list including all (grouped) shapes. You can edit a shape name by double-click or by hitting `F2` after selecting a shape from the list. [See MS-docs for more info.](https://support.microsoft.com/en-us/office/use-the-selection-pane-to-manage-objects-in-documents-a6b2fd3e-d769-46c1-9b9c-b94e04a72550)
@@ -544,6 +560,19 @@ pres.addSlide('images', 2, (slide) => {
 });
 ```
 
+This will also auto-crop the image to the new width and height,
+based on the container aspect ratio, derived from the original image
+and using the new image width and height based on the files loaded into
+the presentation media folder using .loadMedia():
+
+```ts
+pres.addSlide('images', 2, (slide) => {
+  slide.modifyElement('Image Placeholder', [
+    ModifyImageHelper.setRelationTargetCover('feather.png', pres),
+  ]);
+});
+```
+
 Find more examples on image manipulation:
 
 - [Add external image](https://github.com/singerla/pptx-automizer/blob/main/__tests__/add-external-image.test.ts)

src/helper/compute-src-rect.ts

@@ -2,7 +2,12 @@ type SrcRect = { l?: number; t?: number; r?: number; b?: number }; // thousandth
 const K = 100000;
 
 // Convert the source rectangle to fractions of the image width and height for easier calculation
-function toFractions(src: SrcRect): { l: number; t: number; r: number; b: number } {
+function toFractions(src: SrcRect): {
+  l: number;
+  t: number;
+  r: number;
+  b: number;
+} {
   return {
     l: (src.l ?? 0) / K,
     t: (src.t ?? 0) / K,
@@ -15,7 +20,7 @@ function toFractions(src: SrcRect): { l: number; t: number; r: number; b: number
 export function inferContainerAr(
   oldImageWidth: number,
   oldImageHeight: number,
-  currentSrcRect: SrcRect // read from the slide; missing attrs mean 0
+  currentSrcRect: SrcRect, // read from the slide; missing attrs mean 0
 ): number {
   const { l, t, r, b } = toFractions(currentSrcRect);
   const wf = 1 - (l + r);
@@ -28,10 +33,15 @@ export function inferContainerAr(
 export function computeSrcRectForNewImage(
   containerAr: number,
   newImageWidth: number,
-  newImageHeight: number
+  newImageHeight: number,
 ): SrcRect {
   const newAr = newImageWidth / newImageHeight;
-  if (!isFinite(containerAr) || !isFinite(newAr) || containerAr <= 0 || newAr <= 0) {
+  if (
+    !isFinite(containerAr) ||
+    !isFinite(newAr) ||
+    containerAr <= 0 ||
+    newAr <= 0
+  ) {
     return { l: 0, t: 0, r: 0, b: 0 };
   }
 
@@ -51,4 +61,4 @@ export function computeSrcRectForNewImage(
     // equal AR -> no crop needed
     return { l: 0, t: 0, r: 0, b: 0 };
   }
-}
+}

src/helper/modify-image-helper.ts

@@ -1,10 +1,13 @@
 import { XmlElement } from '../types/xml-types';
 import { ImageStyle } from '../types/modify-types';
 import slugify from 'slugify';
-import {imageSize } from 'image-size';
+import { imageSize } from 'image-size';
 import fs from 'fs';
 import { IPresentationProps } from '../interfaces/ipresentation-props';
-import { computeSrcRectForNewImage, inferContainerAr } from './compute-src-rect';
+import {
+  computeSrcRectForNewImage,
+  inferContainerAr,
+} from './compute-src-rect';
 
 export default class ModifyImageHelper {
   /**
@@ -27,29 +30,29 @@ export default class ModifyImageHelper {
    * the presentation media folder using .loadMedia()
    * @param filename name of target image in root template media folder.
    * @param pres presentation properties (to access the root template archive)
-   * @param newImageWidth width of the new image
-   * @param newImageHeight height of the new image
    */
   static setRelationTargetCover = (
     filename: string,
     pres: IPresentationProps,
   ) => {
     return async (element: XmlElement, arg1: XmlElement): Promise<void> => {
-
       const newTarget = '../media/' + slugify(filename);
       const originalTarget = arg1.getAttribute('Target');
       const originalTargetPath = originalTarget.replace('../', 'ppt/');
       const originalImageDimensions = { width: 100, height: 100 };
       const newImageDimensions = { width: 100, height: 100 };
 
-
       // Get the new image dimensions, using the rootTemplate mediafiles array,
       // since we have it loaded into the presentation media folder using .loadMedia()
       // If we don't find the media file, we warn, but continue
       try {
-        const mediaFile = pres.rootTemplate.mediaFiles.find(file => file.file === filename);
-        if(!mediaFile) {
-          throw new Error("Media file not found in template archive in path: " + filename);
+        const mediaFile = pres.rootTemplate.mediaFiles.find(
+          (file) => file.file === filename,
+        );
+        if (!mediaFile) {
+          throw new Error(
+            'Media file not found in template archive in path: ' + filename,
+          );
         }
         const buffer = fs.readFileSync(mediaFile.filepath);
         const _dimensions = imageSize(buffer);
@@ -58,53 +61,70 @@ export default class ModifyImageHelper {
       } catch (error) {
         console.warn("Couldn't find media file in template archive in path.");
       }
-      
+
       // Find the original image dimensions using the original target path from the original slide
       // using the rootTemplate archive file system and get the image dimensions.
       // If we don't find the original image, we warn, but continue
       // If we find the original image, we get the image dimensions and use this to reverse calculate
       // the aspect ratio and then use the new image dimensions to calculate and set the new crop on srcRect.
       // This results in the image being cropped in the image container to match the aspect ratio of the new image.
       try {
-        if(pres.rootTemplate.archive.fileExists(originalTargetPath)) {
-          const originalImage = await pres.rootTemplate.archive.read(originalTargetPath, "nodebuffer");
+        if (pres.rootTemplate.archive.fileExists(originalTargetPath)) {
+          const originalImage = await pres.rootTemplate.archive.read(
+            originalTargetPath,
+            'nodebuffer',
+          );
           const _dimensions = imageSize(originalImage);
           originalImageDimensions.width = _dimensions.width;
           originalImageDimensions.height = _dimensions.height;
         } else {
-          throw new Error("Original image not found from template archive in path: " + originalTargetPath);
+          throw new Error(
+            'Original image not found from template archive in path: ' +
+              originalTargetPath,
+          );
         }
-  
+
         const srcRect = element.getElementsByTagName('a:srcRect')[0];
         const srcRectLeft = srcRect.getAttribute('l');
         const srcRectTop = srcRect.getAttribute('t');
         const srcRectRight = srcRect.getAttribute('r');
         const srcRectBottom = srcRect.getAttribute('b');
-  
+
         const currentSrcRect = {
           l: srcRectLeft ? Number(srcRectLeft) : 0,
           t: srcRectTop ? Number(srcRectTop) : 0,
           r: srcRectRight ? Number(srcRectRight) : 0,
           b: srcRectBottom ? Number(srcRectBottom) : 0,
-        }
-  
-        const containerAr = inferContainerAr(originalImageDimensions.width, originalImageDimensions.height, currentSrcRect);
-        
-        const newSrcRect = computeSrcRectForNewImage(containerAr, newImageDimensions.width, newImageDimensions.height);
-        
+        };
+
+        const containerAr = inferContainerAr(
+          originalImageDimensions.width,
+          originalImageDimensions.height,
+          currentSrcRect,
+        );
+
+        const newSrcRect = computeSrcRectForNewImage(
+          containerAr,
+          newImageDimensions.width,
+          newImageDimensions.height,
+        );
+
         srcRect.setAttribute('l', String(newSrcRect.l));
         srcRect.setAttribute('t', String(newSrcRect.t));
         srcRect.setAttribute('r', String(newSrcRect.r));
         srcRect.setAttribute('b', String(newSrcRect.b));
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.warn("Skipped setting relation target cropped due to an error: " + errorMessage);
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        console.warn(
+          'Skipped setting relation target cropped due to an error: ' +
+            errorMessage,
+        );
       }
-      
-      arg1.setAttribute('Target', newTarget);
 
+      arg1.setAttribute('Target', newTarget);
     };
-  }
+  };
 
   /*
     Update an existing duotone image overlay element (WIP)