apollonius - npm Package Compare versions

Comparing version 1.2.0 to 1.2.1

package.json

 {
   "name": "apollonius",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Solves Apollonius' problem by finding a fourth circle tangent to three given circles",
@@ -33,11 +33,13 @@ "type": "module",
   "keywords": [
-    "geometry",
+    "2d",
+    "math",
+    "tangent",
     "circle",
-    "apollonius",
-    "apollonian",
-    "tangent",
-    "math",
+    "sphere",
     "packing",
+    "solver",
     "layout",
-    "2d"
+    "geometry",
+    "apollonius",
+    "apollonian"
   ],
@@ -44,0 +46,0 @@ "author": "Akseli Palén <[e-mail]>",

README.md

@@ -12,11 +12,13 @@ # apollonius
 
-The `apollonius` module provides a function to find a circle that touches three known circles. The resulting circle is an exact solution to the [Problem of Apollonius](https://en.wikipedia.org/wiki/Problem_of_Apollonius) also known as *Apollonian problem*. In other words, it finds a circle that is *tangent to* each of the known three circles. The function is robust: the three known circles can be placed freely and are allowed to overlap each other.
+The `apollonius` module provides a function to find a circle that touches three known circles. The resulting circle is an exact solution to the [Problem of Apollonius](https://en.wikipedia.org/wiki/Problem_of_Apollonius) also known as *apollonian problem*. In other words, it finds a circle that is *tangent* to each of the known three circles. The function is robust: the known circles can be placed freely and are allowed to overlap each other.
 
-Because a circle can be either internally or externally tangent to another circle, the problem of Apollonius has eight solutions in total, one for each combination of tangency rules of the three circles. The function here finds only one solution per call but can be used to find all eight.
+Because a circle can be either internally or externally tangent to another circle, the problem of Apollonius has eight solutions in total, one for each combination of tangency rules of the three circles. The function here finds one solution per call but can be configured to find all eight.
 
-The function is very efficient. It has time complexity of O(1) and does not call any trigonometric functions.
+The function is very efficient. It has time complexity of *O(1)* and does not call any trigonometric functions.
 
-[Installation](#installation) – [Usage](#usage) – [API](#api) – [Contribute](#contribute)
+Try out [the demo!](https://axelpale.github.io/apollonius/demo.html)
 
+[Installation](#installation) – [Usage](#usage) – [Special Cases](#special-cases) – [API](#api) – [Contribute](#contribute)
 
+
 ## Installation
@@ -43,3 +45,3 @@
 
-Alternatively, install via a [script tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script). Download the minified UMD bundle `apollonius-1.2.3.min.js` at [releases](https://github.com/axelpale/apollonius/releases) or at [unpkg.com](https://www.unpkg.com/apollonius@1.2.0/dist/apollonius.min.js) and host it alongside your HTML:
+Alternatively, install via a [script tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script). Either download a minified bundle from [releases](https://github.com/axelpale/apollonius/releases) and host it alongside your HTML, like below, or use [Unpkg CDN](https://www.unpkg.com/).
 
@@ -51,3 +53,4 @@ ```
     // ...
-    var c = apollonius.solve(...)
+    var circle = apollonius.solve(...)
+    // ...
   })
@@ -57,5 +60,12 @@ </script>
 
-The bundle declares the global variable `window.apollonius`. Above we wrote the script tag with [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer) to allow browsers to continue parsing the page while loading the bundle. The `DOMContentLoaded` event is fired after the browser has loaded all the asset files. The usage of `defer` and `DOMContentLoaded` is not required but is a good convention when your app has lots of assets.
+[Unpkg CDN](https://www.unpkg.com/) URL is good for some quick hands-on development but it is not recommended for production:
 
+```
+<script src="https://www.unpkg.com/apollonius/dist/apollonius.min.js" defer></script>
+...
+```
 
+The bundle declares the global variable `window.apollonius`. Usage of [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer) attribute and [DOMContentLoaded](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event) event is optional although a good convention.
+
+
 ## Usage
@@ -94,21 +104,32 @@
 ![Figure: Internally Tangent Circles](doc/example_internal.png "The result circle must be internally tangent to the circles 1 and 3 and externally tangent to the circle 2.")
+_**Figure:** The resulting circle `c` is internally tangent to the known circles `c1` and `c3` and externally tangent to the known circle `c2`._
 
-The resulting circle `c` is internally tangent to the known circles `c1` and `c3` and externally tangent to the known circle `c2`. Note that while the known circles can have negative radii, the output circle always has positive or zero radius.
+Note that while the known circles can have negative radii, the output circle always has positive or zero radius.
 
 
-### Special cases
+## Special cases
 
-The fourth circle cannot be found for some configurations of known circles. These configurations may appear when there are:
+The fourth circle cannot be found for some configurations of known circles. The function will then return `null`. These configurations may appear when there are:
 
 - **nested circles:** a circle cannot be internally or externally tangent two or more nested circles at the same time.
-- **identical circles along a line:** when three same-size circles are arranged along a straight line, the radius of the tangent circle would go to infinity.
+- **identical circles along a line:** when three same-size circles are arranged along a straight line, the radius of the tangent circle would go to infinity and thus its radial center could not be defined.
 
-If the fourth circle cannot be found, the function will return `null`.
+These unsolvable configurations are illustrated below.
 
-The fourth circle may reduce to a point (a circle with zero radius) in some configurations of known circles. These configurations may appear when there are:
+![Figure: special cases: nested circles and circles along a line](doc/example_special_case_unsolvable.png "a) nested circles; b) circles along a line")
+_**Figure:** cases of unavailable solution and infinite-radius solution. The wicks mark the tangency rules of the circles. A) no tangent circle can be found that is tangent to a circle and two nested circles at the same time. B) if the tangency points form a straight line then the solution circle radius becomes infinite._
 
+In addition, the fourth circle may reduce to a point (a circle with zero radius) in some configurations of known circles. These configurations may appear when there are:
+
 - **identical stacked circles:** The known circles are exact copies of each other. Then the externally tangent circle reduces to an arbitrary point on the shared circumference of the known.
 - **circles intersect at a single point:** The known circles share only one common point. Then the externally tangent circle reduces to that point.
 
+These zero radius yielding configurations are illustrated below.
 
+![Figure: special cases: stacked circles and intersecting circles](doc/example_special_case_point-like.png "a) stacked circles; b) circles intersect at a point")
+_**Figure:** cases of infite number of solutions and a zero-radius solution. A) In theory, a stack of three identical circles have an infinite number of solutions of arbitrary radius. The function will arbitrarily pick a zero-radius point at the common circumference. B) Unique zero-radius solution can be found at the mutual intersection point of all three circles._
+
+For further details, see [Special cases of Apollonius' problem](https://en.wikipedia.org/wiki/Special_cases_of_Apollonius%27_problem) at Wikipedia.
+
+
 ## API
@@ -124,5 +145,5 @@
 - c2
-  - an object `{ x, y, r }`
+  - an object `{ x, y, r }`, representing a circle in 2D. The properties `x`, `y`, and `r` must be real numbers and are allowed to be negative.
 - c3
-  - an object `{ x, y, r }`
+  - an object `{ x, y, r }`, representing a circle in 2D. The properties `x`, `y`, and `r` must be real numbers and are allowed to be negative.
 
@@ -139,3 +160,3 @@ Returns:
 
-The function `apollonius.solve` handles various (special cases)[#specialcases] by switching to alternative algorithms when certain internal variables turn zero. However, the variables rarely exactly equal zero because of rounding errors caused by floating point arithmetics. Computation with near-zero numbers would cause arbitrary results and therefore a margin of safety is needed.
+The function `apollonius.solve` handles various [special cases](#specialcases) by switching to alternative algorithms when certain internal variables turn zero. However, the variables rarely exactly equal zero because of rounding errors caused by floating point arithmetics. Computation with near-zero numbers would cause arbitrary results and therefore a margin of safety is needed.
 
@@ -174,3 +195,3 @@ The `epsilon` defines the numerical margin in which an almost zero number is treated as zero. The default value for epsilon is `1e-10`. You can adjust it if needed. For example, if you know the properties of your circles will be large numbers then a larger epsilon may yield more robust behavior near the special cases:
 
-The following tools, works, and projects had important role in the development of the package.
+The following tools, projects, and works had an important role in the development of the package.
 
@@ -177,0 +198,0 @@ - [Maxima](https://maxima.sourceforge.io/) symbolic algebra tookit was used during formulation of the algorithm.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

22407

increased by8.39%

Number of lines in readme file

198

increased by11.86%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes