Post without Account — your post will be reviewed, and if appropriate, posted under Anonymous. You can also use this link to report any problems registering or logging in.

RT 98576 - General notes on testing Content.pm

  • 5 Replies
  • 2139 Views
*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
RT 98576 - General notes on testing Content.pm
« October 21, 2016, 03:50:47 PM »
Subject:    General notes on testing Content.pm
Date:    Tue, 2 Sep 2014 21:47:40 -0400
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry

PDF::API2  v2.022  Perl 5.16.3  Windows 7   Severity: Normal

While testing, updating, and documenting Content.pm and some related components, I encountered some issues that should be thought about:

  • I initially changed the circle() and ellipse() methods to call deg2rad() for the 0-to-360 degree sweeps, but they broke. I think we need more testing for any place that uses deg2rad() and might get angles that are 360 degrees apart. At the least, the documentation for those methods  should warn about this.
  • In most graphics packages I've encountered, a "spline" is a curve that passes THROUGH all the points given. It's not a Bezier cubic curve with synthesized control points (as far as I can tell, although it IS often cubic). If what PDF::API2 is doing is not normally considered a spline, perhaps this particular construct should be renamed.
  • The code does very little testing and validation of input parameters. It would be easy to send an application into outer space by feeding it incorrect  inputs. Of course, the downside is that more robust code runs more slowly.
  • In many places in the POD, dimensions (lengths) were specified as INTEGER points. I believe this is incorrect, and REAL values are just as acceptable. If this is so, we need to check where REAL inputs for dimensions are coerced into INTEGERs (unexpected loss of precision).
  • It would be nice to find official word on how much graphics and text states overlap in functionality (and how they affect each other, if at all), and add this to the POD. save() and restore() are of special interest -- do they cover everything, or are they separate for graphics and text?
  • The OO architecture is somewhat misleading, as it appears that there can be only one graphics object and one text object. I'm not sure what happens when you have multiple of each -- at the PDF level, I think they resolve down to affecting the same global graphic or text state, and different PDF::API2 global settings (e.g., miterlimit settings in two different graphics objects) could apply at different times. At the least, this needs to be clearly stated in the POD.
  • I have written a Content.pl program that exercises and demonstrates many of the methods (including those not in content.t), and provided it to the maintainer. My hope is that eventually it could be the core for a full-fledged PDF document or book explaining and documenting PDF::API2.
#
Wed Feb 17 18:27:11 2016 steve [...] deefs.net - Correspondence added

There are too many items here for one ticket, so I'm closing it.

If spline is poorly named (I'm not knowledgeable in this area), it can be deprecated and replaced by a better-named function.  Please provide documentation and a suggestion for a new name for the existing function.

Input validation is a worthwhile addition, and a massive project.  Patches with tests and helpful error messages are welcome.
#
Wed Feb 17 18:27:12 2016 The RT System itself - Status changed from 'new' to 'open'
#
Wed Feb 17 18:27:12 2016 steve [...] deefs.net - Status changed from 'open' to 'rejected'
#
Subject:    [rt.cpan.org #98576]
Date:    Thu, 18 Feb 2016 16:03:50 -0500
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry

Would you be willing to cover these items if they're broken up into single item bug reports?

I'm not a mathematician, but I think what the spline() function is doing MAY be called a B-spline (or an approximation spline). If that's the case, it could just be clarified with a note in the POD. It would be nice to get some graphics experts participating in this discussion...

Per discussion on bogen() method (98541), we could decide to simply die() upon any invalid input found, rather than trying to fix it up and soldier on. In some cases, users might find it useful to be able to fix up bad input, so we might want to think about hooks for handling these cases, or at least, provide commented-out code. E.g., for bogen with too small of radius, have code to set the radius to the minimum allowable size.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
Re: RT 98576 - General notes on testing Content.pm
« Reply #1: November 14, 2016, 08:50:05 PM »
Some fixed in 3.001

  • spline() POD entry discusses the spline type in detail.
  • A few parameter checks have been added.

The rest of this is major work, and will have to wait for a later release. I would also like to get some feedback from the community on what they'd like to see changed.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
Re: RT 98576 - General notes on testing Content.pm
« Reply #2: November 18, 2016, 10:01:52 PM »
We could add one or more new spline types (cubic, etc. that pass through all points), but I'd like to discuss this with the community before proceeding.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
Re: RT 98576 - General notes on testing Content.pm
« Reply #3: March 28, 2017, 02:26:45 PM »
Regarding unnecessary restriction of data to INTEGER type, I looked around and now I can seem to find any such instances, either in the code or in the POD. Perhaps someone cleaned them up already. I'll keep an eye open, but for now it looks like this item is a dead letter.

Content.pl has been released in examples/, as has ContentText.pl.

The OO applicability, and text vs. graphics overlap, are still open issues. At the very least, they need to be better documented.

deg2rad() still needs to be looked at, to make sure 0 and 360 degree angles are different, if that is the cause of bugs when explicit conversion code was replaced with deg2rad() calls.
« Last Edit: March 31, 2017, 04:35:59 PM by Phil »

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
Re: RT 98576 - General notes on testing Content.pm
« Reply #4: April 12, 2017, 08:55:21 AM »
I have split out the discussion on text and graphics objects into its own topic (CTS 7 - text and graphics objects), as it seems to be worth a major topic of its own. Please continue discussion on this subject over there.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
Re: RT 98576 - General notes on testing Content.pm
« Reply #5: April 12, 2017, 12:57:36 PM »
Regarding bullet 1, I have added warnings to code (and POD) that deg2rad() wraps around at 360 degrees to 0. This is why the original concern about closed arcs (circle and ellipse: 0–360 degrees) not being able to use deg2rad(). It is unlikely that other uses of deg2rad() will encounter problems (possibly excepting some color specifications that use a color angle), but the POD update should keep people out of trouble.