New feature: Ellipse rotation

[MUYUM]

Hi

For one project I need to rotate ellipse. This is currently not supported by jsPDF, therefore I invested some time to extend the code.

It's my first time contributing to jsPDF, therefore I haven't pushed anything to GitHub. It's better if "admin" does it and I will check the changes later.

Current code in jsPDF:

API.__private__.ellipse = API.ellipse = function(x, y, rx, ry, style) {
    if (
      isNaN(x) ||
      isNaN(y) ||
      isNaN(rx) ||
      isNaN(ry) ||
      !isValidStyle(style)
    ) {
      throw new Error("Invalid arguments passed to jsPDF.ellipse");
    }
    var lx = (4 / 3) * (Math.SQRT2 - 1) * rx,
      ly = (4 / 3) * (Math.SQRT2 - 1) * ry;

    moveTo(x + rx, y);
    curveTo(x + rx, y - ly, x + lx, y - ry, x, y - ry);
    curveTo(x - lx, y - ry, x - rx, y - ly, x - rx, y);
    curveTo(x - rx, y + ly, x - lx, y + ry, x, y + ry);
    curveTo(x + lx, y + ry, x + rx, y + ly, x + rx, y);

    putStyle(style);
    return this;
  };

Extended code (ellipse is rotated):

API.__private__.ellipse = API.ellipse = function(x, y, rx, ry, style, phi) {
      if (
        isNaN(x) ||
        isNaN(y) ||
        isNaN(rx) ||
        isNaN(ry) ||
        !isValidStyle(style)
      ) {
        throw new Error("Invalid arguments passed to jsPDF.ellipse");
      }
      var lx = (4 / 3) * (Math.SQRT2 - 1) * rx,
          ly = (4 / 3) * (Math.SQRT2 - 1) * ry;

      var R = (phi || 0) * Math.PI / 180; // Rotation angle (clockwise) converted to Radians

      // Array of points to be rotated
      var P = [
            { X: x + rx, Y: y      },
            { X: x + rx, Y: y - ly },
            { X: x - lx, Y: y - ry },
            { X: x - rx, Y: y + ly },
            { X: x + lx, Y: y + ry },
            { X: x + lx, Y: y - ry },
            { X: x - rx, Y: y - ly },
            { X: x - lx, Y: y + ry },
            { X: x + rx, Y: y + ly },
            { X: x     , Y: y - ry },
            { X: x - rx, Y: y      },
            { X: x     , Y: y + ry },
        ];

      // Rotate ellipse around center (clockwise)
      P.forEach(M =>
      {
          var tX = M.X - x;
          var tY = M.Y - y;

          M.mX = x + tX * Math.cos(R) - tY * Math.sin(R);
          M.mY = y + tX * Math.sin(R) + tY * Math.cos(R);
      });

      // Draw ellipse with curves: Use rotated coordinates
      moveTo (P[0].mX, P[0].mY);
      curveTo(P[1].mX, P[1].mY, P[5].mX, P[5].mY, P[ 9].mX, P[ 9].mY);
      curveTo(P[2].mX, P[2].mY, P[6].mX, P[6].mY, P[10].mX, P[10].mY);
      curveTo(P[3].mX, P[3].mY, P[7].mX, P[7].mY, P[11].mX, P[11].mY);
      curveTo(P[4].mX, P[4].mY, P[8].mX, P[8].mY, P[ 0].mX, P[ 0].mY);

      putStyle(style);
      return this;
    };

Can you please update jsPDF with the extended code. I will have a look afterwards to get idea which parts of the code were changed.

Best regards

[HackbrettXXX]

You can easily rotate an ellipse by setting a transformation matrix:

doc.setCurrentTransformationMatrix(new Matrix( ...rotation Matrix... )
doc.ellipse(...)

You might need to switch to advanced API mode, first:

doc.advancedAPI(() => {
  // your code
})

[MUYUM]

Ok, thanks. I was not aware of this feature.

Best regards

[joshi1983]

@MUYUM did you eventually implement the rotated ellipse using a transformation matrix? I would greatly appreciate seeing an example. I'm trying to but struggling with a few challenges.

1. My attempt to rotate around an arbitrary point isn't working. The centre of the rotated ellipse arcs as I change the rotation angle when it should be stationary. My rotation matrix seems correct because the ellipse rotates on the intended angle. The x y parameters to the ellipse method and/or my translation matrices appear to be the problem. I tried using various translation matrices along with the rotation matrix but the ellipse's intended centre keeps moving with respect to the rotation angle.
2. I couldn't find a good way to undo my changes to the transformation matrix. Graphics libraries like OpenGL, HTML5 Canvas context2d have push and pop methods for transformation matrices but I couldn't find a similar convenience in jsPDF. I call setCurrentTransformationMatrix with the inversed matrices in reverse order which works properly. Despite this working correctly, it seems insanely complex and inefficient. Isn't there a way of accessing the transformation matrix directly instead of multiplying the hidden matrix using setCurrentTransformationMatrix?
3. Is it possible to have a single jsPDF Matrix representing both a rotation and translation? I called multiply on a rotation matrix with a translation matrix but the result didn't do both. I guess the problem is stems from only 6 of the 9 numbers in the matrix can vary in jsPDF's Matrix. I worked around this problem by using more than 1 matrix but this seems like an odd limitation.

[zengxiaoluan]

@MUYUM did you eventually implement the rotated ellipse using a transformation matrix? I would greatly appreciate seeing an example. I'm trying to but struggling with a few challenges.

1. My attempt to rotate around an arbitrary point isn't working. The centre of the rotated ellipse arcs as I change the rotation angle when it should be stationary. My rotation matrix seems correct because the ellipse rotates on the intended angle. The x y parameters to the ellipse method and/or my translation matrices appear to be the problem. I tried using various translation matrices along with the rotation matrix but the ellipse's intended centre keeps moving with respect to the rotation angle.
2. I couldn't find a good way to undo my changes to the transformation matrix. Graphics libraries like OpenGL, HTML5 Canvas context2d have push and pop methods for transformation matrices but I couldn't find a similar convenience in jsPDF. I call setCurrentTransformationMatrix with the inversed matrices in reverse order which works properly. Despite this working correctly, it seems insanely complex and inefficient. Isn't there a way of accessing the transformation matrix directly instead of multiplying the hidden matrix using setCurrentTransformationMatrix?
3. Is it possible to have a single jsPDF Matrix representing both a rotation and translation? I called multiply on a rotation matrix with a translation matrix but the result didn't do both. I guess the problem is stems from only 6 of the 9 numbers in the matrix can vary in jsPDF's Matrix. I worked around this problem by using more than 1 matrix but this seems like an odd limitation.

@joshi1983 you can write the code below, might match your commands:

pdf.saveGraphicsState() // Save the current graphics state on the graphics state stack

pdf.setCurrentTransformationMatrix(matrix) // the matrix is what your wants
pdf.ellipse()

pdf.restoreGraphicsState() // Restore the graphics state by removing the most recently saved state from the stack and making it the current state

[Josello82]

This issue is closed, but I'm trying to add a rotated ellipse and I'm facing some problems.
Could you please provide a more detailed example of how to calculate the transformation matrix to create a rotated ellipse and calculating the new x and y points?

const x = 50
const y = 50
const rX = 50;
const rY = 100;

pdf.ellipse(x, y, rX, rY); // unrotated ellipse, this works fine.

// Imagine a want to rotate the ellipse 30 degrees from it's center point. I have this code, but it's not working.
const angleInRadians = 30 * (Math.PI / 180);

const a = Math.cos(angleInRadians);
const b = Math.sin(angleInRadians);
const c = -Math.sin(angleInRadians);
const d = Math.cos(angleInRadians);
const e = 0;
const f = 0;

pdf.saveGraphicsState();
pdf.setCurrentTransformationMatrix(pdf.Matrix(a, b, c, d, e, f));
pdf.ellipse(x, y, rX, rY); // this ellipse is drawn in a wrong place
pdf.restoreGraphicsState();

Thanks in advance.

[zengxiaoluan]

@Josello82 Hi, you can use this code to give a try.

let doc = new jsPDF();

const x = 50;
const y = 50;
const rX = 50;
const rY = 100;

doc.advancedAPI(() => {
  doc.saveGraphicsState();

  let { a, b, c, d, e, f } = new DOMMatrix()
    .translate(x, y)
    .rotate(30)
    .scaleSelf(rX, rY);

  doc.setCurrentTransformationMatrix(doc.Matrix(a, b, c, d, e, f));

  doc.ellipse(0, 0, 1, 1); // make it as a unit ellipse and transform by above matrix
  doc.fill();
  
  doc.restoreGraphicsState();
});

[Josello82]

@Josello82 Hi, you can use this code to give a try.

let doc = new jsPDF();

const x = 50;
const y = 50;
const rX = 50;
const rY = 100;

doc.advancedAPI(() => {
  doc.saveGraphicsState();

  let { a, b, c, d, e, f } = new DOMMatrix()
    .translate(x, y)
    .rotate(30)
    .scaleSelf(rX, rY);

  doc.setCurrentTransformationMatrix(doc.Matrix(a, b, c, d, e, f));

  doc.ellipse(0, 0, 1, 1); // make it as a unit ellipse and transform by above matrix
  doc.fill();
  
  doc.restoreGraphicsState();
});

I have had to do a few small changes, but it works like a charm! Thank you so much!