Pythagoras is a collection of geometry classes that aims to provide performant,
portable geometry routines for projects that cannot make use of java.awt.geom
(for example for use in GWT projects or Android projects). In addition to
original work, it contains code adapted from the Apache Harmony project and
the Clyde library.
API documentation is available.
Pythagoras can be obtained via Maven Central: com.samskivert:pythagoras:1.4.3
.
Or you can download the pre-built jar file.
Some restructuring of the java.awt.geom
classes was undertaken to meet
certain design goals.
The library is specialized on the primitive types rather than attempting to
support all types in a single class hierarchy. pythagoras.f
and
pythagoras.d
provide equivalent functionality using 32-bit and 64-bit
floating point values throughout. pythagoras.i
is specialized on int and
contains none of the curved geometry classes.
The need for defensive copying is minimized by the existence of read-only
interfaces for each geometric primitive, which allow no mutation of the
entity. Thus a consumer that requires only to read the attributes of, for
example, a Rectangle
can accept an IRectangle
to indicate to the caller
that it will not (and indeed cannot) mutate the supplied entity. Similarly, a
read-only interface can be returned to a private internal field without fear
that the recipient will mutate it and wreak havoc. Note that the interfaces
have a very small, but non-zero, performance cost versus direct use of the
mutable classes. Use the interfaces anyway and then profile your application
to determine whether there are places where you need to sacrifice code
clarity and safety on the altar of higher performance.
The library supports garbage creation avoidance (for applications which are
sensitive to garbage collection pauses, like video games). For example, in
cases where entities return a Rectangle
containing their bounds, a
corresponding method exists which accepts a Rectangle
into which to write
the bounds. Further work is needed here, as some of the implementation
internals create garbage that could be avoided.
The library attempts to minimize the size of its instances by avoiding the inclusion of any fields that are not essential to the function of a particular geometric entity. For example, no cached hash codes or cached computed bounds are maintained.
Helper methods associated with a given geometric primitive are separated into
a utility class for each primitive. For example line-related primitives are
in a class named Lines
.
Pythagoras is released under the Apache License, Version 2.0 which can be found
in the LICENSE
file and at http://www.apache.org/licenses/LICENSE-2.0 on the
web.