
Class: Point
Object

+Magnitude

+ArithmeticValue

+Point

+Point3D
 Package:
 stx:libbasic
 Category:
 GraphicsGeometry
 Version:
 rev:
1.117
date: 2023/08/21 10:06:48
 user: cg
 file: Point.st directory: libbasic
 module: stx stcclassLibrary: libbasic
I represent a point in 2D space. Or I can be used to represent
an extent (of a rectangle, for example), in which case my xcoordinate
represents the width, and ycoordinate the height of something.
The x and y coordinates are usually numbers.
[Instance variables:]
x <Number> the xcoordinate of myself
y <Number> the ycoordinate of myself
copyrightCOPYRIGHT (c) 1989 by Claus Gittinger
All Rights Reserved
This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice. This software may not
be provided or otherwise made available to, or used by, any
other person. No title to or ownership of the software is
hereby transferred.
constants

> unity">unity

return the neutral element for multiplication

> zero">zero

return the neutral element for addition
instance creation

> decodeFromLiteralArray:">decodeFromLiteralArray: anArray

create & return a new instance from information encoded in anArray.
Redefined for faster creation.
Usage example(s):
Point
decodeFromLiteralArray:#(Point 10 10)


> r:angle:">r: distance angle: angle

create and return a new point given polar coordinates.
The angle is given in degrees.
OBSOLETE STX interface, use #r:theta:
** This is an obsolete interface  do not use it (it may vanish in future versions) **

> r:degrees:">r: distance degrees: angle

create and return a new point given polar coordinates.
The angle is given in degrees (ccw).
Added for Squeak compatibility
Usage example(s):

> r:theta:">r: distance theta: angleInRadians

create and return a new point given polar coordinates.
The angle is given in radians (ccw)
Usage example(s):
Point r:100 theta:0
Point r:100 theta:Float pi/2


> readFrom:onError:">readFrom: aStringOrStream onError: exceptionBlock

return the next Point from the (character)stream aStream;
skipping all whitespace first; return the value of exceptionBlock,
if no point can be read.
Usage example(s):
Point readFrom:'1.234 @ 5.678'
Point readFrom:'( 1.234 @ 5.678 )'
Point readFrom:'1'
Point readFrom:'1' onError:[1@1]
Point readFrom:'fooBar' onError:[0@0]
Point readFrom:'( 10 × 20 )'
Point readFrom:'( 10 , 20 )'
Point readFrom:'( 10 ; 20 )'
Point readFrom:'( (10/2) × 20 )'
Point readFrom:'( (1/3) @ (1/2) )'


> x:y:">x: newX y: newY

create and return a new point with coordinates newX and newY
queries

> isBuiltInClass">isBuiltInClass

return true if this class is known by the runtimesystem.
Here, true is returned for myself, false for subclasses.
CompatibilitySqueak

> adhereTo:">adhereTo: aRectangle

If the receiver lies outside aRectangle, return the nearest point on the boundary of the rectangle,
otherwise return self.

> area">area

compute the area of a rectangle with myself taken as extent

> asFloatPoint">asFloatPoint
( an extension from the stx:libcompat package )

Answer a new Point that is the receiver's x and y as floatingpoint numbers.

> asLargerPowerOfTwo">asLargerPowerOfTwo
( an extension from the stx:libcompat package )

return a point where both coordinates are rounded up to
the next larger power of two.
ATTN: it is not yet clear, what to do when a coordinate is already a powerOfTwo
Usage example(s):
(10 @ 10) asLargerPowerOfTwo
(10 @ 10) asSmallerPowerOfTwo


> asSmallerPowerOfTwo">asSmallerPowerOfTwo
( an extension from the stx:libcompat package )

return a point where both coordinates are rounded up to
the next smaller power of two.
ATTN: it is not yet clear, what to do when a coordinate is already a powerOfTwo
Usage example(s):
(10 @ 10) asLargerPowerOfTwo
(10 @ 10) asSmallerPowerOfTwo
(16 @ 16) asLargerPowerOfTwo
(16 @ 16) asSmallerPowerOfTwo


> maxDimension">maxDimension

Answer the larger of the two dimensions.
accessing

> r:degrees:">r: distance degrees: angle

initialize the new point given polar coordinates.
The angle is given in degrees (ccw).
Added for Squeak compatibility

> r:theta:">r: distance theta: angleInRadians

initialize the new point given polar coordinates.
The angle is given in radians (ccw).
Added for Squeak compatibility

> x">x

return the x coordinate

> x:">x: newX

set the x coordinate to be the argument, aNumber.
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver.

> x:y:">x: newX y: newY

set both the x and y coordinates.
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver.

> y">y

return the y coordinate

> y:">y: newY

set the y coordinate to be the argument, aNumber.
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver.

> z">z
( an extension from the stx:libbasic2 package )

return the z coordinate  here zero
coercing & converting

> coerce:">coerce: anObject

convert the argument aNumber into an instance of the receiver's class and return it.

> generality">generality

return the generality value  see ArithmeticValue>>retry:coercing:
comparing

> <">< aPointOrNumber

return true if the receiver is above and to the left
of the argument, aPointOrNumber
Usage example(s):
notice the funny result if one coordinate has the same value ...
(3@3) < (4@4) > true
(3@4) < (4@4) > false
(4@3) < (4@4) > false
(3@3) <= (4@4) > true
(3@4) <= (4@4) > true
(4@3) <= (4@4) > true
(4@4) <= (4@4) > true
(3@4) > (4@4) > false
(4@4) >= (3@4) > true
(4@4) > (3@4) > false


> =">= aPointOrNumber

return true if the receiver represents the same point as
the argument, aPoint

> >">> aPointOrNumber

return true if the receiver is below and to the right
of the argument, aPoint

> hash">hash

return a number for hashing

> isLeftOrAbove:">isLeftOrAbove: aPoint

return true if the receiver is above or to the left
of the argument, aPoint.
When sorting this enumerates points from left to right and top to bottom

> max:">max: aPoint

return the lower right corner of the rectangle uniquely defined by
the receiver and the argument, aPoint

> min:">min: aPoint

return the upper left corner of the rectangle uniquely defined by
the receiver and the argument, aPoint
converting

> @">@ z
( an extension from the stx:libbasic2 package )

return a 3D coordinate from the receiver
Usage example(s):
10 @ 20 @ 30
(10 @ 20) @ 0


> asComplex">asComplex

Return a complex number whose real and imaginary components are the x and y
coordinates of the receiver.

> asFloat">asFloat

raises an error

> asFraction">asFraction

raises an error

> asFractionalLayout">asFractionalLayout
( an extension from the stx:libview2 package )

return a LayoutOrigin from the receiver,
treating the receiver coordinates as fractional parts
(i.e. relative to superview).
Usage example(s):
(0@0.5) asFractionalLayout
(0@0.5) asLayout
(0@10) asLayout
(0@10) asOffsetLayout


> asFractionalLayoutWithOffset:">asFractionalLayoutWithOffset: aPoint

return a LayoutOrigin from the receiver,
treating the receiver coordinates as fractional parts
(i.e. relative to superview).
Usage example(s):
(0@0.5) asFractionalLayoutWithOffset:(3@3)


> asIntegerPoint">asIntegerPoint

returns a point with truncated (towards zero)
Usage example(s):
(1.5 @ 2.5) asIntegerPoint
(1.5 @ 2.5) asIntegerPoint


> asLayout">asLayout
( an extension from the stx:libview2 package )

return a LayoutOrigin from the receiver.
If the receiver coordinates are between 0 and 1, take
them as fractional parts (relative to superview).
Otherwise, treat them as absolute offsets.
Notice: in 10.5.x LayoutOrigin is not yet released.
Usage example(s):
(0@0.5) asFractionalLayout
(0@0.5) asLayout
(0@10) asLayout
(0@10) asOffsetLayout


> asOffsetLayout">asOffsetLayout
( an extension from the stx:libview2 package )

return a LayoutOrigin from the receiver,
treating the receiver coordinates as absolute offsets.
Usage example(s):
(0@0.5) asFractionalLayout
(0@0.5) asLayout
(0@10) asLayout
(0@10) asOffsetLayout


> asPoint">asPoint

return the receiver as Point  this is the receiver

> asRectangle">asRectangle

return a zerowidth rectangle consisting of origin
and corner being the receiver
Usage example(s):

> corner:">corner: aPoint

return a rectangle whose origin is self and corner is aPoint

> extent:">extent: aPoint

return a rectangle whose origin is self and extent is aPoint

> fromLiteralArrayEncoding:">fromLiteralArrayEncoding: encoding

read my values from an encoding.
The encoding is supposed to be of the form: (Point xValue yValue)
Usage example(s):
Point new fromLiteralArrayEncoding:#(Point 10 20)


> literalArrayEncoding">literalArrayEncoding

encode myself as an array, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.
The encoding is: (Point xValue yValue)
Usage example(s):
Point new fromLiteralArrayEncoding:#(Point 10 20)
(10@20) literalArrayEncoding


> rectangleRelativeTo:preferred:">rectangleRelativeTo: aRectangle preferred: prefRectHolder

compute a displayRectangle, treating the receiver like a
layoutorigin. This allows point to be used interchangable with
LayoutOrigins.
Usage example(s):
consider the case, where a view has a preferred extent of 50@50
and is to be positioned in its superview which has size 100@100.
For absolute origin:
(10@20) rectangleRelativeTo:(0@0 corner:100@100) preferred:(0@0 corner:50@50)
for relative origin:
(0.5@0.5) rectangleRelativeTo:(0@0 corner:100@100) preferred:(0@0 corner:50@50)

destructive transformations

> scaleBy:">scaleBy: aScale

scale the receiver, by replacing coordinates by the product
of the receiver's coordinates and the scale (a Point or Number).
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver.

> translateBy:">translateBy: anOffset

translate the receiver, by replacing coordinates by the sum
of the receiver's coordinated and the scale (a Point or Number).
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver.
double dispatching

> differenceFromPoint:">differenceFromPoint: aPoint

return the difference from aPoint  self.
(not used with points, but with subclass instances)

> productFromPoint:">productFromPoint: aPoint

return the product of aPoint * self.
(not used with points, but with subclass instances)

> quotientFromPoint:">quotientFromPoint: aPoint

return the quotient of aPoint / self.
(not used with points, but with subclass instances)

> sumFromPoint:">sumFromPoint: aPoint

return the sum of aPoint + self.
(not used with points, but with subclass instances)
inspecting

> inspectorValueStringInListFor:">inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )

returns a string to be shown in the inspector's list
interpolating

> interpolateTo:at:">interpolateTo: end at: amountDone

Interpolate between the instance and end after the specified amount has been done (0  1).
i.e. given a line segment deom the receiver to end,
return the coordinate of a point which is amountDone (a fraction) along the line
Usage example(s):
(10@10) interpolateTo:(20@20) at:0.5
(10@10) interpolateTo:(20@20) at:0.3
(0@0) interpolateTo:(0@20) at:0.5
(0@0) interpolateTo:(0@20) at:0 => 0@0 => the start point
(0@0) interpolateTo:(0@20) at:1 => 0@20 => the end point
(0@0) interpolateTo:(0@20) at:0.5 => 0.0@10.0 => the center point
(0@0) interpolateTo:(20@20) at:0.5 => 10.0@10.0 => the center point

misc

> abs">abs

return a new point with my coordinates taken from the absolute values.

> ceiling">ceiling

return a new point with my coordinates truncated towards positive infinity.
Return the receiver if its coordinates are already integral.
Usage example(s):
(1.5 @ 2.6) ceiling => 2@3
(1.5 @ 2.6) ceiling => 2@2
(1.5 @ 2.6) ceiling => 1@2
(1 @ 2) ceiling => 1@2


> floor">floor

return a new point with my coordinates truncated towards negative infinity.
Return the receiver if its coordinates are already integral.
Usage example(s):
(1.5 @ 2.6) floor => 1@2
(1.5 @ 2.6) floor => 1@3
(1.5 @ 2.6) floor => 2@3
(1.5 @ 2.4) floor => 1@2
(1 @ 2) floor => 1@2


> quadrant">quadrant

return the number of the quadrant containing the receiver.
quadrants are named as follows:
^ 2  3
Y 
1  0
X >
Q: what is to be returned if any coordinate is 0 ?
Usage example(s):
(1@1) quadrant
(1@1) quadrant
(1@1) quadrant
(1@1) quadrant
(0@0) quadrant


> quadrantContaining:">quadrantContaining: aPoint

return the number of the quadrant containing aPoint placing
the receiver at the origin, where the quadrants are numbered as
follows:
^ 2  3
Y 
1  0
X >
This can be used for polygon operations (see Foley for examples).
Usage example(s):
(10 @ 10) quadrantContaining:(15 @ 15)
(10 @ 10) quadrantContaining:(5 @ 5)
(10 @ 10) quadrantContaining:(5 @ 15)
(10 @ 10) quadrantContaining:(15 @ 5)


> rounded">rounded

return a new point with my coordinates rounded to the next integer.
Return the receiver if its coordinates are already integral.
Usage example(s):
(1.5 @ 2.6) rounded => 2@3
(1.5 @ 2.4) rounded => 2@2
(1 @ 2) rounded => 1@2


> truncateTo:">truncateTo: aNumber

return a new point with my coordinates truncated towards zero to the next
multiple of aNumber.
Bad name: should be called truncatedTo: because it returns a new instance
Usage example(s):
(10 @ 10) truncateTo:2 => 10@10
(10.5 @ 10.5) truncateTo:2 => 10@10
(10.5 @ 12.5) truncateTo:2 => 10@12
(10.5 @ 12.5) truncateTo:2 => 10@12
(10.5 @ 12.5) truncateTo:2 => 10@12
(10.5 @ 13.5) truncateTo:2 => 10@12
(10.5 @ 13.9) truncateTo:2 => 10@12


> truncated">truncated

return a new point with my coordinates truncated as integer.
Return the receiver if its coordinates are already integral.
Usage example(s):
(10 @ 10) truncated => 10@10
(10.5 @ 10.5) truncated => 10@10
(10.5 @ 12.5) truncated => 10@12
(10.5 @ 12.5) truncated => 10@12
(10.5 @ 12.5) truncated => 10@12

point functions

> crossProduct:">crossProduct: aPoint

Return a number that is the cross product of the receiver and the
argument, aPoint.

> dist:">dist: aPoint

return the distance between aPoint and the receiver.

> dotProduct:">dotProduct: aPoint

return a number that is the dot product of the receiver and
the argument, aPoint. That is, the two points are
multiplied and the coordinates of the result summed.

> fourNeighbors">fourNeighbors

Modified (format): / 17072017 / 14:20:40 / cg

> grid:">grid: gridPoint

return a new point with coordinates grided (i.e. rounded to the
nearest point on the grid)

> nearestIntegerPointOnLineFrom:to:">nearestIntegerPointOnLineFrom: point1 to: point2

return the closest integer point to the receiver on the line
determined by (point1, point2)much faster than the more
accurate version if the receiver and arguments are integer points.
This method was found in the Manchester goody library.
Usage example(s):
120@40 nearestIntegerPointOnLineFrom: 30@120 to: 100@120
0@0 nearestIntegerPointOnLineFrom: 10@10 to: 100@100


> nearestPointIn:">nearestPointIn: aPointCollection

return the point from aPointCollection which is
closest to the receiver.
Usage example(s):
120@40 nearestPointIn:{10@40 . 20@40 . 150@40} => 150@40
120@40 nearestPointIn:{10@40 . 20@40 . 150@40 . 130@50} => 130@50


> normalized">normalized

interpreting myself as the endPoint of a 0@0 based vector,
return the endPoint of the corresponding normalized vector.
(that is the endPoint of a vector with the same direction but length 1)
Usage example(s):
(10 @ 10) normalized
(1 @ 1) normalized
(10 @ 0) normalized
(0 @ 10) normalized
(10 @ 0) normalized
(0 @ 10) normalized
(0 @ 0) normalized


> transposed">transposed

return a new point with x and y coordinates exchanged
polar coordinates

> angle">angle

return the receiver's angle (in degrees) in a polar coordinate system.
(i.e. the angle of a vector from 0@0 to the receiver).
OBSOLETE ST/X interface; use theta for ST80 compatibility.
** This is an obsolete interface  do not use it (it may vanish in future versions) **

> degrees">degrees

return the receiver's angle (in degrees) in a polar coordinate system.
(i.e. the angle of a vector from 0@0 to the receiver).
The angle is counted counterclockwise, starting with 0 for a horizontal
line (i.e. 0@0 > 100@0 has an angle of 0 and 0@0 > 0@100 has an angle of 90).
Added for Squeak compatibility.
Usage example(s):
(1@1) degrees
(2@1) degrees


> r">r

return the receiver's radius in a polar coordinate system.
I.e. the length of a vector from 0@0 to the receiver
Usage example(s):
Usage example(s):
(1@1) r > 1.4142135623731
(2@1) r > 2.23606797749979
(2@0) r > 2.0
(0@2) r > 2.0
(2@2) r > 2.82842712474619
(2@2) r > 2.82842712474619


> theta">theta

return the receiver's angle (in radians) in a polar coordinate system.
(i.e. the angle of a vector from 0@0 to the receiver)
Usage example(s):
(1@1) theta
(2@1) theta
(2@1) theta
(2@1) theta
(0@1) theta

printing & storing

> printOn:">printOn: aStream

append a printed representation of the receiver to aStream

> storeOn:">storeOn: aStream

append my storeString to aStream
testing

> isFinite">isFinite

return true, if the receiver is a finite point
I.e. both coordinates are not NaN and not +/INF

> isInfinite">isInfinite

return true, if the receiver has an infinite coordinate

> isPoint">isPoint

return true, if the receiver is some kind of point
transformations

> *">* scale

Return a new Point that is the coordinate product of the
receiver and scale (which is a Point or Number).
See also cross and dot products

> +">+ translation

Return a new Point that is the sum of the
receiver and translation (which is a Point or Number).
Usage example(s):
(10 @ 20) + (5 @ 10) => 15@30
(10 @ 20) + (5 @ 5) => 15@25
(10 @ 20) + 5 => 15@25
(10 @ 20) + (5 + 10i) => 15@30


> "> translation

Return a new Point that is the difference of the
receiver and translation (which is a Point or Number).
Usage example(s):
(10 @ 20)  (5 @ 10) => 5@10
(10 @ 20)  (5 @ 5) => 5@15
(10 @ 20)  5 => 5@15
(10 @ 20)  (5 + 10i) => 5@10

Usage example(s):
Modified (comment): / 02072022 / 14:00:20 / cg


> /">/ scale

Return a new Point that is the integer quotient of the
receiver and scale (which is a Point or Number).

> //">// scale

Return a new Point that is the quotient of the
receiver and scale (which is a Point or Number).

> negated">negated

return a new point with my coordinates negated
i.e. the receiver mirrored at the origin
Usage example(s):

> reciprocal">reciprocal

return a new point where the coordinates are
the reciproce of mine

> rotateBy:about:">rotateBy: angle about: center

Return a new point, generated by rotating the receiver
counterClockWise by some angle in radians around the given center point.
Even though Point.theta is measured CW,
this rotates with the more conventional CCW interpretation of angle.
CG: bad naming: should be named 'rotatedBy:', as this is nondestructive
Usage example(s):
(10@10) rotateBy:Float pi about:0@0
(10@0) rotateBy:Float pi about:0@0


> rotatedBy:about:">rotatedBy: angle about: center

Return a new point, generated by rotating the receiver
counterClockWise by some angle in radians around the given center point.
Even though Point theta is measured CW,
this rotates with the more conventional CCW interpretation of angle

> scaledBy:">scaledBy: aScale

return a new Point that is the product of the
receiver and scale (which is a Point or Number).

> transformedBy:">transformedBy: aMatrix

return a new point which is me transformed by aMatrix

> translatedBy:">translatedBy: anOffset

return a copy of the receiver which is translated (i.e. moved)
by anOffset, aPoint or Number.
(i.e. receiver + anOffset).
