« Changelog History


paper.js v0.10.0 Release Notes

  • Preamble

    🚀 This is a huge release for Paper.js as we aim for a version 1.0.0 release later this year. As of this version, all notable changes are documented in the 🔄 change-log following common CHANGELOG conventions. Paper.js now also adheres to Semantic Versioning.

    There are many items in the changelog (and many more items not in the changelog) so here a high-level overview to frame the long list of changes:

    • Boolean operations have been improved and overhauled for reliability and efficiency. These include the path functions to unite, intersect, subtract, exclude, and divide with another path.

    • ✅ There was a large amount of work implementing test coverage under QUnit.

    • Mouse and key handling has been re-engineered and extended to work with view. Many outstanding bugs have been fixed with mouse and key handling.

    • 💻 Many SVG-handling enhancements and bug-fixes, including handling browser- specific interpretations of the SVG standard, have been added.

    • There are API name changes for more consistency as well as some required by changes in the EcmaScript 6 standard (e.g., Symbol → SymbolDefinition).

    • Even though it is not new, since version 0.9.22 Paper.js no longer resizes the canvas to match the view. The canvas must be resized independently.

    Thank you all for using Paper.js, submitting bugs and ideas, and all those that contribute to the code.

    🔄 Changed

    • Significant overhaul and improvements of boolean path operations PathItem#unite(), #subtract(), #intersect(), #exclude(), #divide():
      • Improve handling of self-intersecting paths and non-zero fill-rules.
      • Handle operations on identical paths.
      • Improve handling of near-collinear lines.
      • Handle self-intersecting paths that merely "touch" themselves.
      • Handle situations where all encountered intersections are part of overlaps.
    • Methods that accepted a time parameter or boolean second parameter causing the argument to be interpreted as curve-time instead of offset are now separate functions with distinct names (#563):
      • Curve#getNormalAt(time, true) → #getNormalAtTime(true)
      • Curve#divide() → #divideAt(offset) / #divideAtTime(time)
      • Curve#split() → #splitAt(offset) / #splitAtTime(time)
      • Curve#getParameterAt(offset) → #getTimeAt(offset)
      • Curve#getParameterOf(point) → getTimeOf(point)
      • Curve#getPointAt(time, true) → #getPointAtTime(time)
      • Curve#getTangentAt(time, true) → #getTangentAtTime(time)
      • Curve#getNormalAt(time, true) → #getNormalAtTime(time)
      • Curve#getCurvatureAt(time, true) → #getCurvatureAtTime(time)
      • CurveLocation#parameter → #time
      • Path#split(offset/location) → #splitAt(offset/location)
    • Significant improvement of reliability of bezier fat-line clipping code in PathItem#getIntersections() and #getCrossings().
    • PathItem#smooth() now accepts an options.type string specifying which smoothing algorithm to use: 'asymmetric' (default), 'continuous', 'catmull-rom', and 'geometric' (#338).
    • PathItem#flatten(): argument has been changed from tolerance (maximum allowed distance between points) to flatness (maximum allowed error) (#618).
    • ⚡️ Update internal Acorn JavaScript parser to 0.5.0, the last small version.
    • 🏗 Transition to Gulp based build process.
    • ⚡️ Update QUnit to 1.20.0.
    • ⚡️ Update to JSDOM 8.3.0, to benefit from integrated image and canvas support.
    • 🔨 Complete refactoring of keyboard event handling to increase reliably when handling special keys.
    • 🔨 Complete refactoring of mouse-event handling on item and view, to better handle event propagation, default behavior and Item#removeOn() calls.
    • Simplify and streamline the mouse-handling code on Tool (#595).
    • Mouse handlers can to return false to call event.stop(), stopping event propagation and prevent the default browser behavior.
    • 0️⃣ event.preventDefault() is called by default after any handled mouse mouse events, except 'mousemove', and only on a 'mousedown' event if the view or tool respond to 'mouseup'.
    • Switch to the new HTML5 Page Visibility API when detecting invisible documents and canvases.
    • 💅 Rename #windingRule to #fillRule on Item and Style.
    • Do not replace existing named child reference on Item#children with new one when the name is identical.
    • Limit the effects of #strokeScaling to PathItem and Shape (#721).
    • 👻 Throw an exception if arguments to #smooth() are segments or curves from incorrect paths.
    • 📇 Rename Matrix#concatenate() to #append() and preConcatenate() to #prepend().
    • 👉 Make Matrix#shiftless() and #orNullIfIdentity() internal functions.
    • ⚡️ De-bounce internal View#update() calls to minimize the number of times a canvas is redrawn (#830, #925).
    • Symbol now clashes with ES6 definition of Symbol and has been changed (#770):
      • Symbol → SymbolDefinition
      • PlacedSymbol → SymbolItem
      • Symbol#definition → SymbolDefinition#item
      • PlacedSymbol#symbol → SymbolItem#definition
    • 💅 Don't serialize deprecated Style#font property.
    • 💅 Don't serialize text-styles in non-text items (#934).
    • 💅 Changed argument parameter to time for Postscript-style drawing commands.
    • 0️⃣ Item#clone(): optional argument is now an options object with defaults {insert: true, deep: true}. insert controls whether the clone is inserted into the project and deep controls whether the item's children are cloned. The previous boolean optional argument is still interpreted as the insert option (#941).
    • Matrix properties #b and #c have been reversed to match common standard.
    • 💅 #importSVG(): improve handling of style inheritance for nested <defs>.
    • 🚚 Move PaperScript#execute() URL argument into options.url (#902).
    • PaperScript: Only translate == to equals() calls forPoint,Sizeand Color` (#1043).

    ➕ Added

    • 💻 Use unified code-base for browsers, Node.js, Electron, and anything in-between, and enable npm install for browser use (#739).
    • 🚀 Start using automatic code testing and deployment of prebuilt versions through Travis CI.
    • 👕 Reach JSHint compliance and include regular linting in Travis CI tests.
    • ✅ Use QUnit tests for leaked globals.
    • Define code format standards in .editorconfig file
    • ➕ Add support for running without a canvas for Web Workers, Node.js (#561, #582, #634).
    • ➕ Add support for all common mouse events to View.
    • ➕ Add support for 'keydown' and 'keyup' events to View (#896).
    • ➕ Add View#requestUpdate() function to minimize number of actual canvas redraw.
    • ➕ Add View#matrix to allow matrix transformation to be accessed and modified directly on the view (#832).
    • Multiple additions to SVG export (#exportSVG()):
      • Support { precision: value } option.
      • Support #fillRule through the SVG fill-rule attribute.
      • Support #blendMode through the CSS mix-blend-mode attribute.
    • Various additions to #getItems() on Project and Item:
      • Add support for { recursive: false } as a way to prevent iterating over all children of children.
      • Add support for { match: function() {} }, so the match function can be passed in combination with other options.
    • ➕ Add Item#copyAttributes() and Item#copyContent(), and use them in Item#clone().
    • ➕ Add optional insert boolean argument to Path#toShape(), Shape#toPath(), Item#rasterize(). Default is to insert, set to false to prevent the created item from being inserted into the scene graph.
    • ➕ Add visual item comparison to QUnit, through rasterization and Resemble.js diffing.
    • ➕ Add many unit tests for known edge cases in boolean operations and curve intersections.
    • ➕ Add Project#addLayer() and Project#insertLayer() (#903).
    • Layers may now be given names and be accessed through project.layers[name] (#491).
    • ➕ Add Matrix#prepended() and #appended() to return copies of the modified matrix.
    • ✅ Shape#hitTest(): Add boolean option options.stroke (#911).
    • 📄 Insert version number into docs.
    • 👌 Support Raster#onLoad() events on Raster#setImage() now (#924).
    • ➕ Add Raster#onError() event support (#849).
    • 👍 Allow the control of automatic updating of the canvas through View#autoUpdate (default: true)(#921).
    • 0️⃣ Set 1px default strokeWidth for SVG imports to fix IE/Edge default (#467).
    • ImportSVG() passes imported SVG data to onLoad callback as second parameter.
    • ➕ Add #interpolate for Segment, Path, and CompoundPath (#624).
    • Implement CompoundPath#flatten(), #simplify(), #smooth() (#727).
    • ✅ Implement #hitTestAll() to return all items that were hit (#536).
    • #importSVG() implements option.onError callback (#969).
    • settings.insertItems controls whether newly created items are inserted or not (default: true).
    • ➕ Add #importSVG() option.insert (default: true) to control insertion (#763).
    • ➕ Add new options to #exportSVG() to control output bounds and transformation matrix (#972).
    • 👍 Allow Item#position to be selected via Item#position.selected (#980).
    • ➕ Add tolerance argument to Path#join(path, tolerance).
    • ➕ Add Curve#getOffsetAtTime(time), as the reverse of Curve#getTimeAt(offset).
    • ➕ Add Raster#loaded to reflect the loading state of its image.

    🛠 Fixed

    • 🛠 Fix calculations of Item#strokeBounds for all possible combinations of Item#strokeScaling and Item#applyMatrix for Path, Shape and SymbolItem, along with correct handling of such strokes in Item#hitTest() (#697, #856, #1014).
    • 💻 Make new code-base unified for Node.js/browser work with module bundlers like Webpack (#986).
    • 👌 Improve hit-testing and #contains() checks on path with horizontal lines (#819).
    • 👌 Improve reliability of Path#getInteriorPoint() in rare edge-cases.
    • ✅ Handle non-reversible matrices in Item#hitTest() (#617).
    • 🛠 Fix various issues with adding and removing of segments in paths (#815).
    • 👌 Support bubbling up of doubleclick events on Group (#834).
    • 🛠 Fix wrong #key values in key-events that do not match character (#881).
    • 🛠 Fix keyboard event handling of control and meta keyboard sequences and special character handling (#860).
    • 🏁 Handle incorrect mouse event on ctrl-alt-del key sequence on Chrome/Windows (#800).
    • Do not rasterize items if the resulting raster will be empty (#828).
    • 🛠 Fix SVG serialization in JSDOM 7.0.0 and newer (#821).
    • Correctly handle gradients in SVG import on Firefox (#666).
    • Consistently interpret curves as straight or not-straight (#838).
    • 🐎 Switch blendMode to 'lighter' in Candy Crash example for better performance (#453).
    • Don't block touch actions when using paper in JavaScript mode (#686).
    • Convert touch event coordinates to project coordinates (#633).
    • 🛠 Fix exceptions when a top-level layer is selected.
    • ✅ Don't allow layers to turn up in hit-tests (#608).
    • Maintain Raster#source correctly on Node.js (#914).
    • Boolean operations correctly handle open Path items within CompoundPath (#912).
    • Don't modify an array of child items passed to CompoundPath#insertChildren() when it is a child items array of a CompoundPath.
    • ✅ Correctly handle #strokeScaling in Shape hit-tests (#697).
    • 👌 Support clip-masks in hit-testing (#671).
    • 🛠 Fix incorrect #hitTest() and #contains() cases (#819, #884).
    • 📚 Update documentation to note appropriate use for #simplify() (#920).
    • 👍 #importSVG() now supports percentage dimensions and gradientUnits="objectBoundingBox". (#954, #650).
    • Group items with clip-masks now calculate correct bounding boxes (#956).
    • Calling event.stopPropagation() in 'mousedown' handler no longer prevents 'mousedrag' events (#952).
    • Draw Item shadows when #shadowBlur is zero (#955).
    • 🛠 Fixes for web site examples (#967).
    • Prevent Item bounds from permanently collapsing to 0 when applying non- invertible transformations (#558).
    • 💻 Scaling shadows now works correctly with browser- and view-zoom (#831).
    • Path#arcTo() correctly handles zero sizes.
    • #importSVG() handles onLoad and onError callbacks for string inputs that load external resources (#827).
    • #importJSON() and #exportJSON() now handle non-Item objects correctly (#392).
    • #exportSVG() now exports empty paths if used as a clip-mask.
    • #importJSON() no longer generates callstack exceeded exceptions (#764).
    • 🛠 Fix problems with group selection structures after Group#importJSON() (#785).
    • 🛠 Fix an issue in Item#importJSON() where #parent is null when calling it on existing, already inserted items (#1041).
    • Correct issue when using paper-core in Node.js (#975).
    • 🛠 Fix event.delta on mousedrag events (#981).
    • 👌 Improve handling of XML attribute namespaces for IE's XMLSerializer() (#984).
    • 🚚 Make sure Item#removeChildren() fully removes children (#991).
    • 👌 Improve handling of event propagation on View and Item (#995).
    • #importSVG(): Improve handling of viewBox.
    • 🔀 Make sure all named item lookup structures are kept in sync (#1009).
    • Convert absolute local gradient URLs to relative ones (#1001).
    • 🛠 Fix TypeError in Path#unite() (#1000).
    • 👍 Allow the selection of a Path item's bounds without selecting the segments (#769).
    • 🛠 Fix wrong indices in Item#insertChildren(), when inserting children that were previously inserted in the same parent (#1015).
    • ➕ Add capability to PathItem#closePath() to handle imprecise SVG data due to rounding (#1045).
    • 👌 Improve reliability of fat-line clipping for curves that are very similar (#904).
    • 👌 Improve precision of Numerical.solveQuadratic() and Numerical.solveCubic() for edge-cases (#1085).

    ✂ Removed

    • Canvas attributes "resize" and "data-paper-resize" no longer cause paper to resize the canvas when the viewport size changes; Additional CSS styles are required since 0.9.22, e.g.:
      /* Scale canvas with resize attribute to full size */
  canvas[resize] {
      width: 100%;
      height: 100%;
  }
    • 🚚 Legacy Color constructors (removed in 0.9.25): GrayColor, RgbColor, HsbColor, HslColor, and GradientColor. These have been replaced with corresponding forms of the Color constructor.
    • Undocumented function Project#addChild() that added a layer to a project. It is replaced by Project#addLayer() and Project#insertLayer().

    🗄 Deprecated

    • 💅 #windingRule on Item and Style → #fillRule
    • Curve#getNormalAt(time, true) → #getNormalAtTime(true)
    • Curve#divide() → #divideAt(offset) / #divideAtTime(time)
    • Curve#split() → #splitAt(offset) / #splitAtTime(time)
    • Curve#getParameterAt(offset) → #getTimeAt(offset)
    • Curve#getParameterOf(point) → getTimeOf(point)
    • Curve#getPointAt(time, true) → #getPointAtTime(time)
    • Curve#getTangentAt(time, true) → #getTangentAtTime(time)
    • Curve#getNormalAt(time, true) → #getNormalAtTime(time)
    • Curve#getCurvatureAt(time, true) → #getCurvatureAtTime(time)
    • CurveLocation#parameter → #time
    • Path#split(offset/location) → #splitAt(offset/location)
    • Symbol → SymbolDefinition
    • PlacedSymbol → SymbolItem
    • Symbol#definition → SymbolDefinition#item
    • PlacedSymbol#symbol → SymbolItem#definition
    • Project#symbols → #symbolDefinitions
    • Matrix#concatenate → #append
    • Matrix#preConcatenate → #prepend
    • Matrix#chain → #appended
    • GradientStop#rampPoint → #offset