Class CMUtilities
CMUtilities Class
General utilities.
Copyright (C) 2020, Humboldt State University, Jim Graham
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see
Enumerated Types
CMUtilities.COORDINATE_UNITS_DD=0CMUtilities.COORDINATE_UNITS_DMS=1
CMUtilities.COORDINATE_UNITS_METERS=2
CMUtilities.COORDINATE_UNITS_FEET=3
CMUtilities.COORDINATE_UNITS_PIXELS=4 - displays the pixel level coordinates for debugging
CMUtilities.COORDINATE_UNITS_ZOOM=5 - displays the zoom level for debugging
Static Functions
| Returns | Function | Throws |
|---|---|---|
| AbsolutePosition(TheElement, Left, Top, Width, Height) | ||
| Coordinate | GetElementCoordinate() | |
| Colors | GetColorsFromArrays(FeatureValues, TheColors, Intervals) | |
| LegendElement | AddLegend(TheCanvasElement, TheColors, LegendLabels, X,Y,Width,Height) | |
| Mean | GetMean(TheArray) | |
| StdDev | GetStdDev(TheArray) | |
| {Min,Max} | GetMinMax(TheArray) | |
| {Min,Max,Bins,Labels} | GetHistogram(TheArray, NumBins) | |
| Quantiles | GetQuantiles(TheHistogram, NumGroups) | |
| FlippedArray | FlipArray(TheArray) | |
| Sort(TheArray) | ||
| InsertIntoSortedArray(TheArray, TheValue, AllowDuplicates) | ||
| Flag | ArraysEqual(TheArray1, TheArray2) | |
| CoordinateArray | GetRegularPolygon(NumPoints, Size, CenterX, CenterY, StartAngle) | |
| CoordinateArray | GetStar(NumPoints, Size, CenterX, CenterY, StartAngle) | |
| TheElement | CreateLabelControl(Text, Position, X, Y) | |
| TheElement | CreateInfoWindow(ID, Left, Top, Width, Height, Text) | |
| LineIndex | InPolyline(RefX, RefY, TheCoordinates, Tolerance) | |
| InPolylinePoint() | ||
| Flag | BoundsIncludes(ExteriorBounds, InteriorBounds) | |
| Flag | BoundsOverlap(Bounds1, Bounds2) | |
| ClonedBounds | CloneBounds(TheBounds) | |
| TheBounds | AddToBounds(TheBounds, NewBounds) | |
| ExpandBounds(TheBounds, Amount) | ||
| Flag | InsideAPolygon(RefX, RefY, Xs, Ys, NumPoints) | |
| Bounds | GetPolygonBounds(Xs, Ys, NumPoints) | |
| Distance | GetLength(X1,Y1,X2,Y2) | |
| Result | IntersectionOfTwoLineSegments(X1,Y1,X2,Y2) | |
| Seconds | GetSeconds() | |
| ClonedObject | Clone() | |
| CoordinateString | GetCoordinateString(-, -, -, -, -) | |
| QuadArea | GetQuadArea(Xs, Ys) | |
| Angle | GetAngleBetweenLineSegments(X1,Y1,X2,Y2,X3,Y3) | |
| Angle | GetAngleBetweenVectors(X1,Y1,X2,Y2) | |
| Flag | IsValid(Value) | |
| RemoveElementsChildren(TheElement) | ||
| Index | IndexOfChildInElement(Child, Parent) | |
| RemoveChildElement(Element, Parent) | ||
| ContentsElement(Parent, TargetChild) |
Static Functions
AbsolutePosition(TheElement, Left, Top, Width, Height)
Make an element be positioned abosolutely
Parameters:
TheElement - the DOM element to position
Left - left position in pixels
Top - Top position in pixels
Width - Width in pixels
Height - Height in pixels
Coordinate=GetElementCoordinate()
Moves the global coordinate to be local with the specified element
Returns: Coordinate - Global coordinate as {x,y}
Colors=GetColorsFromArrays(FeatureValues, TheColors, Intervals)
Creates an array of colors from a set of feature values, a set of colors, and defined intervals.
The returned result
Used to create legends.
Parameters:
FeatureValues - array of values for the features, typically from an attribute
TheColors - array of colors for the FeatureValues
Intervals - optional array of intervals that bracket the colors. If not specified, the intervals will be defined to cover the range of FeatureValues
Returns: Colors - { LegendLabels,FeatureColors} where LegendLabels an array of names appropriate for a legend and FeatureColors is an array to colorize each of the features
LegendElement=AddLegend(TheCanvasElement, TheColors, LegendLabels, X,Y,Width,Height)
Adds a legend to a DOM element. This is a basic legend and this function may be expanded in the future.
Parameters:
TheCanvasElement - the element to add the legend to
TheColors - array of colors for the legend
LegendLabels - labels to go next to the legend colors
X,Y,Width,Height - position and dimensions of the legend in pixels
Returns: LegendElement - a new DOM element.
Mean=GetMean(TheArray)
Get the mean value for the specified array
Parameters:
TheArray - array of numeric values
Returns: Mean - average value of the values in the array
StdDev=GetStdDev(TheArray)
Compute the standard deviation for the values in the array
Parameters:
TheArray - array of numeric values
Returns: StdDev - standard deviation of the values in the array
{Min,Max}=GetMinMax(TheArray)
Get the min and max values from the specified array
Parameters:
TheArray - array of numeric values
Returns: {Min,Max} - null
{Min,Max,Bins,Labels}=GetHistogram(TheArray, NumBins)
Get a histogram with the specified number of bins
Parameters:
TheArray - array of numeric values
NumBins - array of numeric values
Returns: {Min,Max,Bins,Labels} - a histogram in an object with the keys:
Quantiles=GetQuantiles(TheHistogram, NumGroups)
Quantiles are the breaks in a range of values that divides them into
groups that contian an equal number of entries.
Parameters:
TheHistogram - array of countes
NumGroups - number of groups to contain the same number of entries
Returns: Quantiles - array of quantiles
FlippedArray=FlipArray(TheArray)
Reverse the order of the entries in the array.
Parameters:
TheArray
Returns: FlippedArray - Array with entries reversed.
Sort(TheArray)
Sort an array from the lowest to the highest values
Parameters:
TheArray
InsertIntoSortedArray(TheArray, TheValue, AllowDuplicates)
Adds the specified value into TheArray while keeping the array sorted from lowest to highest value.
Parameters:
TheArray - an array that is already sorted
TheValue - the numeric value to insert
AllowDuplicates - true to allow duplicate entries
Flag=ArraysEqual(TheArray1, TheArray2)
Compares the two arrays to see if they are identical
Parameters:
TheArray1
TheArray2
Returns: Flag - true if the arrays are the same length and have equivalent entries
CoordinateArray=GetRegularPolygon(NumPoints, Size, CenterX, CenterY, StartAngle)
Returns an array of coordinates for a regular polygon of the specified
number of points.
Parameters:
NumPoints - 3 for a triangle, 4 for a square, 5 for a pentagon, etc.
Size - Distance from the center to each point in the polygon
CenterX - Center for the polygon
CenterY
StartAngle - 0 to have the first point straight up (north), 90 for east, etc.
Returns: CoordinateArray - Array with first entry as an array of x coordinate values and the second as y coordinate values
CoordinateArray=GetStar(NumPoints, Size, CenterX, CenterY, StartAngle)
Returns the shape of a star
Parameters:
NumPoints
Size
CenterX
CenterY
StartAngle - angle to the first point in degrees (0 is up)
Returns: CoordinateArray - Array with first entry as an array of x coordinate values and the second as y coordinate values
TheElement=CreateLabelControl(Text, Position, X, Y)
Creates a DOM element at the specified location
Parameters:
Text - the text displayed in the element
Position - CSS position parameter
X - pixel-based horizontal position
Y - pixel-based vertical position
Returns: TheElement - DOM element (DIV)
TheElement=CreateInfoWindow(ID, Left, Top, Width, Height, Text)
Dimensions are for the box, the triangle will be placed below it
Parameters:
ID - The name of the balloon element to create (typically each map has a unique ID)
Left - location to tie the tooltip to (typically the X coordinate of the mouse down)
Top - location to tie the tooltip to (typically the Y coordinate of the mouse down)
Width - desired width of the tool tip (in future versions, the tooltip may be smaller
Height - ignored, the tooltip now sizes with it's contents
Text - the HTML to place int he tooltip
Returns: TheElement - DOM element (DIV)
LineIndex=InPolyline(RefX, RefY, TheCoordinates, Tolerance)
Determines if the specified point is within the tolerance of one of the TheCoordinates
Parameters:
RefX - horizontal coordinate value
RefY - vertical coordinate value
TheCoordinates - array of coordinate values where [i][0]=x, [i][1]=y (i.e. the OGS standard)
Tolerance - horizontal coordinate value
Returns: LineIndex - index to a line segement within the poly if it is within Tolerance of the coordinate defined by RefX,RefY
InPolylinePoint()
Returns the index to the point in the polyline that is within Tolerance of RefX, RefY
Flag=BoundsIncludes(ExteriorBounds, InteriorBounds)
Determines if the second bounds is included within the first bounds.
Parameters:
ExteriorBounds
InteriorBounds
Returns: Flag - true if the interior bounds is inside the exterior bounds (they can touch and this can still be true)
Flag=BoundsOverlap(Bounds1, Bounds2)
Returns true if the two bounds objects overlap
Parameters:
Bounds1
Bounds2
Returns: Flag - true if the bounds overlap, false otherwise
ClonedBounds=CloneBounds(TheBounds)
Returns a clone of the specified bounds object.
Parameters:
TheBounds
Returns: ClonedBounds - null
TheBounds=AddToBounds(TheBounds, NewBounds)
Makes sure that the area of the specified bounds is within the returned bounds.
Parameters:
TheBounds
NewBounds
Returns: TheBounds - Bounds with the NewBounds included
ExpandBounds(TheBounds, Amount)
Expands the bounds by the specified amount
Parameters:
TheBounds
Amount - amount to expand the bounds in each direction
Flag=InsideAPolygon(RefX, RefY, Xs, Ys, NumPoints)
Determines if the specified point is within the specified polygon.
This is done by counting the number of line segements from the polygon
that a horiziontal line through the point would intersect with.
If the number of lines is odd, then the point is inside the polygon.
If the number of lines is even, then the point is outside.
Most similar algorithms do not deal with flat lines very well. The problem
is that there can be a flat line to the right of the point. This approach:
- Does not check the start and end points in the FindNumLineCrossingsToTheRight()
function. These are special cased.
- Flat areas are "ignored"
- When the point of interest is at the same Y value as a point in the polygon:
- When the direction of a flat area changes, there is not crossing (peak or valley with a flat top or bottom)
- For non flat areas the approach is the same, if the direction changes, we're on a peak or vally and the number of crossings does not change.
Parameters:
RefX - x coordinate value to test
RefY - y coordinate value to test
Xs - array of x coordinate values, does not need to close
Ys - array of y coordinate values, does not need to close
NumPoints - number of coordinates to test in the array.
Returns: Flag - null
Bounds=GetPolygonBounds(Xs, Ys, NumPoints)
Return the rectangular bounds for the specified polygon
Parameters:
Xs
Ys
NumPoints
Returns: Bounds - Bounds surrounding the polygon
Distance=GetLength(X1,Y1,X2,Y2)
Finds the distance between two points
Parameters:
X1,Y1,X2,Y2 - two coordinates
Returns: Distance - numeric distance between the two points
Result=IntersectionOfTwoLineSegments(X1,Y1,X2,Y2)
Finds the intersection between two line segements
from: http://www-cs.ccny.cuny.edu/~wolberg/capstone/intersection/Intersection%20point%20of%20two%20lines.html
Parameters:
X1,Y1,X2,Y2 - two coordinates
Returns: Result - [0]=RefX, [1]=RefY
Seconds=GetSeconds()
Return the current number of seconds for timing code
Returns: Seconds - number of seconds
ClonedObject=Clone()
Create a clone of the specified object. For non-objects, returns the specified object.
Will do a deep clone on arrays (which are objects in JavaScript) and dictionaries (also objects)
Adapted from: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty
Returns: ClonedObject - null
CoordinateString=GetCoordinateString(-, -, -, -, -)
Gets a text string with the specified units for display.
Parameters:
- RefX - East/West coordinate value
- RefY - North/South coordinate value
- CoordinateUnits - The desired coordinate units from CMUtilities.COORDINATE_UNITS
- TheProjector - Optional projector if the coodinates need to be converted.
- TheView - Optional parameter if the zoom level or pixel location is desired.
Returns: CoordinateString - null
QuadArea=GetQuadArea(Xs, Ys)
Returns the area of the quad described by the four points in 3 dimensional space.
Since the points are not necessiarly co-planar, the calculation uses two triangles.
Parameters:
Xs - x coordinate values ordered as UL, UR, LR, LL
Ys - y coordinate values ordered as UL, UR, LR, LL
Returns: QuadArea - null
Angle=GetAngleBetweenLineSegments(X1,Y1,X2,Y2,X3,Y3)
Computes the angle between two line segments in 2D space
Parameters:
X1,Y1,X2,Y2,X3,Y3
Returns: Angle - in degrees
Angle=GetAngleBetweenVectors(X1,Y1,X2,Y2)
Computes the angle between two vectors in 2D space
Parameters:
X1,Y1,X2,Y2
Returns: Angle - in degrees
Flag=IsValid(Value)
Checks to see if a value is value (i.e. not NaN or null)
(jjg - combine with IsDefined()?)
Parameters:
Value
Returns: Flag - null
RemoveElementsChildren(TheElement)
Removes all the children from a DOM element
Parameters:
TheElement - The parent element that the children will be rmeoved from
Index=IndexOfChildInElement(Child, Parent)
Finds the index to the specified child in the parent DOM element
Parameters:
Child - target element
Parent - parent DOM element
Returns: Index - 1 if the child was not found in the parent
RemoveChildElement(Element, Parent)
Removes a child of a DOM element without generating an error if the child is not in the parent
Parameters:
Element - target element
Parent - parent DOM element
ContentsElement(Parent, TargetChild)
Returns true if the target child element appears anywhere in the DOM tree below the parent.
Parameters:
Parent - parent to check children
TargetChild - child to look for