- Enclosing class:
- SteppedGrid
SteppedGrid
. Stepped grids are configured with a
set of X values and a set of Y values, sorted in ascending order.
The grid is divided into components that represent rectangular
cells. An index (i,j) places the lower left corner of each component
at the location (xs[i], ys[j]), where xs and ys are the arrays of
the X and Y values respectively. The width of a component is
xs[i+1]-xs[i] and the height of a component is ys[j+1]-ys[j],
which implies that the number of I indices is one less than the
number of X values and the number of J indices is one less than
the number of Y values. Each component also has a z value
associated, measured from a base z value for the grid as a whole.
Creating a grid and filling it is tedious except for simple
cases. The SteppedGrid.Builder
class allows a stepped grid to be
specified by providing individual rectangles and assigning
height to them. The SteppedGrid.Builder
supports both open and
closed grids. Open grids consist of a single grid, whereas
closed grids consist of two grids, which will be connected
where appropriate with vertical surfaces. For a closed grid,
rectangles denoted as placeholders are left blank and are to be
filled in by the caller.
The methods used depend on whether the SteppedGrid that will be
created is open or closed (open grids contain a single grid whereas
closed grids contain two, an upper and a lower grid). The methods
addHalfRectangle(double,double,int,Corner,double)
,
addHalfRectangle(double,double,int,Corner,double,boolean)
,
addRectangle(double,double,double,double,double,boolean)
, and
addRectangle(double,double,double,double,double,boolean,boolean)
are used to configure open grids, whereas the methods
addHalfRectangles(double,double,int,Corner,double,double)
,
addHalfRectangles(double,double,int,Corner,double,double,boolean,boolean)
,
addRectangles(double,double,double,double,double,double)
,
addRectangles(double,double,double,double,double,double,boolean,boolean)
,
addRectangle(double,double,double,double,double,boolean)
, and
addRectangle(double,double,double,double,double,boolean,boolean)
are used to configure closed grids.
One method is used for both open and closed grids:
removeRectangles(double,double,double,double)
.
When the rectangles specified by these methods intersect, the
parameters for the rectangle created by the most recent call
are used to configure a grid component.
To configure a SteppedGrid, one simply specifies a sequence
of rectangles and half rectangles. The half rectangles must be
specified after all the full rectangles are specified.
when two rectangles intersect, the data for the component placed
at the intersection will be that specified by the most recent
call to addRectangle, addHalfRectangle, addRectangles,
addHalfRectangles, or removeRectangles. The use of placeholders
is the same as for* SteppedGrid
.
After calls to addRectangle, addRectangles, addHalfRectangle,
addHalfRectangles, and/or removeRectangles, one will call the method
create()
to generate the stepped grids.
For example, if m3d
is an instance of Model3D,
will create a box with a pyramid at its center. The second call to addRectangles overrides the parameters provided by the first call inside a rectangular area 60 by 60 in size that constitutes the base of the pyramid. The second to the last argument in the second call to addRectangles is true, implying that the rectangle specifies a placeholder for the upper grid. The lower grid will be filled as the final argument is false. The empty area is then filled in by calls toSteppedGrid.Builder sgb = new SteppedGrid.Builder(m3d, 10.0, -10.0); sgb.addRectangles(0.0, 0.0, 100.0, 100.0, 0.0, 0.0); sgb.addRectangles(20.0, 20.0, 60.0, 60.0, 0.0, 0.0, true, false); SteppedGrid sg = sgb.create() m3d.addTriangle(50.0, 50.0, 30.0, 20.0, 20.0, 10.0, 80.0, 20.0, 10.0); m3d.addTriangle(50.0, 50.0, 30.0, 80.0, 20.0, 10.0, 80.0, 80.0, 10.0); m3d.addTriangle(50.0, 50.0, 30.0, 80.0, 80.0, 10.0, 20.0, 80.0, 10.0); m3d.addTriangle(50.0, 50.0, 30.0, 20.0, 80.0, 10.0, 20.0, 20.0, 10.0);
Model3D.addTriangle(double,double,double,double,double,double,double,double,double)
.
The resulting object is shown in the following image:
Since a stepped grid implements the Shape3D
interface, one can easily obtain the boundary for a stepped grid
(e.g., a closed stepped grid with placeholders):
Path3D boundary = sg.getBoundary();
If stepped-grid builder is improperly configured, sgb.create()
may throw an exception. The method
P3d.printSteppedGridBuilderCalls(Appendable,String,SteppedGrid.Builder)
can be used to print information about which addRectangle or
addRectangles methods were responsible.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Enumeration naming the corner of a half rectangle. -
Constructor Summary
ConstructorsConstructorDescriptionBuilder
(Model3DOps<?> m3d, double zBase, boolean isUpper) Constructor for creating a partial stepped grid.Builder
(Model3DOps<?> m3d, double zBase1, double zBase2) Constructor for creating a full stepped grid. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addHalfRectangle
(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset) Insert a half rectangle into the upper or lower grid, but not both.void
addHalfRectangle
(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset, boolean placeholder) Insert a half rectangle into the upper or lower grid, but not both, and specifying if the rectangle is a placeholder.void
addHalfRectangles
(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2) Add half rectangles to the upper and lower grids.void
addHalfRectangles
(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2) Add half rectangles to the upper and lower grids, specifying if the half rectangles are placeholders.void
addRectangle
(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper) Add a rectangle to the upper or lower grid.void
addRectangle
(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper, boolean placeholder) Add a rectangle to the upper or lower grid, specifying whether the rectangle is a placeholder.void
addRectangles
(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2) Add rectangles to the upper and lower grids.void
addRectangles
(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2) Add rectangles to the upper and lower grids, specifying whether the rectangles are a placeholders.void
addX
(double x) Add a vertical grid separator at a specified X value.void
addY
(double y) Add a vertical grid separator at a specified Y value.create()
Create a stepped grid and place it in the default model.create
(Model3DOps<?> m3d) Create a stepped grid.int
getIndexFromX
(double x) For a given key get the index into the array thatgetXs()
would return.int
getIndexFromY
(double y) For a given key, get the index into the array thatgetYs()
would return.int
getLengthFromX
(double x1, double x2) Get the number of vertical grid separators to traverse when going between two values of Xint
getLengthFromY
(double y1, double y2) Get the number of horizontal grid separators to traverse when going between two values of YGet a stack trace containing the call to aSteppedGrid.Builder
method that set part of the lower grid so as to cause an exception to be thrown.double
Get the maximum spacing between vertices in the Z direction.Get a stack trace containing the call to aSteppedGrid.Builder
method that set part of the upper grid so as to cause an exception to be thrown.double[]
getXs()
Get the X coordinates delimiting grid elements.double[]
getYs()
Get the Y coordinates delimiting grid elements.boolean
Determine if this stepped grid has a maximum spacing in the Z direction.void
removeRectangles
(double x, double y, double xlength, double ylength) Remove any portions of rectangles that intersect a rectangular area in the upper and/or lower grids.void
setMaxZSpacing
(double spacing) Set the maximum spacing between vertices in the Z direction.
-
Constructor Details
-
Builder
Constructor for creating a partial stepped grid.- Parameters:
m3d
- the modelzBase
- the base height in the Z direction for the grid.isUpper
- true if the grid's outside direction faces up; false if it faces down
-
Builder
Constructor for creating a full stepped grid. This constructor creates a stepped grid with an upper and lower grid.- Parameters:
m3d
- the modelzBase1
- the base height in the Z direction for the upper gridzBase2
- the base height in the Z direction for the lower grid
-
-
Method Details
-
getUpperTrace
Get a stack trace containing the call to aSteppedGrid.Builder
method that set part of the upper grid so as to cause an exception to be thrown.- Returns:
- the stack trace; null if there is no such call or if this builder was created when its model did not allow stack traces.
-
getLowerTrace
Get a stack trace containing the call to aSteppedGrid.Builder
method that set part of the lower grid so as to cause an exception to be thrown.- Returns:
- the stack trace; null if there is no such call or if this builder was created when its model did not allow stack traces.
-
addX
public void addX(double x) Add a vertical grid separator at a specified X value. This increases the total number of grid elements traversed in the X direction by 1.- Parameters:
x
- the value of X
-
addY
public void addY(double y) Add a vertical grid separator at a specified Y value. This increases the total number of grid elements traversed in the Y direction by 1.- Parameters:
y
- the value of Y
-
getLengthFromX
public int getLengthFromX(double x1, double x2) Get the number of vertical grid separators to traverse when going between two values of X- Parameters:
x1
- the starting value of Xx2
- the ending value of X, which must be larger than or equal to x1- Returns:
- the number of grid separators to traverse
-
getLengthFromY
public int getLengthFromY(double y1, double y2) Get the number of horizontal grid separators to traverse when going between two values of Y- Parameters:
y1
- the starting value of Yy2
- the ending value of Y, which must be larger than or equal to y1- Returns:
- the number of grid elements to traverse
-
addHalfRectangles
public void addHalfRectangles(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2) Add half rectangles to the upper and lower grids.- Parameters:
x
- the X coordinate of the lower left corner of the rectangle containing this half rectangley
- the Y coordinate of the lower left corner of the rectangle containing this half rectanglelength
- the number of grid elementsfilledCorner
- the corner within a filled regionzOffset1
- the height in the Z direction measured from the the upper grid's basezOffset2
- the height in the Z direction measured from the the lower grid's base
-
addHalfRectangles
public void addHalfRectangles(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2) Add half rectangles to the upper and lower grids, specifying if the half rectangles are placeholders.- Parameters:
x
- the X coordinate of the lower left corner of the rectangle containing this half rectangley
- the Y coordinate of the lower left corner of the rectangle containing this half rectanglelength
- the number of grid elementsfilledCorner
- the corner within a filled regionzOffset1
- the height in the Z direction measured from the the upper grid's basezOffset2
- the height in the Z direction measured from the the lower grid's baseplaceholder1
- true if the half-rectangle for the upper grid is a placeholder; false if it is notplaceholder2
- true if the half-rectangle for the lower grid is a placeholder; false if it is not
-
addRectangles
public void addRectangles(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2) Add rectangles to the upper and lower grids. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used. The default placeholder flags used by this method have the valuefalse
.- Parameters:
x
- the lower-left X coordinate for the rectangley
- the lower-left Y coordinate for the rectanglexlength
- the length of the rectangle in the X directionylength
- the length of the rectangle in the Y directionzOffset1
- the Z value of the upper-grid's rectangle relative to the base value for its gridzOffset2
- the Z value of the lower-grid's rectangle relative to the base value for its grid
-
addRectangles
public void addRectangles(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2) Add rectangles to the upper and lower grids, specifying whether the rectangles are a placeholders. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used.- Parameters:
x
- the lower-left X coordinate for the rectangley
- the lower-left Y coordinate for the rectanglexlength
- the length of the rectangle in the X directionylength
- the length of the rectangle in the Y directionzOffset1
- the Z value of the upper-grid's rectangle relative to the base value for its gridzOffset2
- the Z value of the lower-grid's rectangle relative to the base value for its gridplaceholder1
- true if the rectangle to be added to the upper grid is a placeholder; false otherwiseplaceholder2
- true if the rectangle to be added to the lower grid is a placeholder; false otherwise
-
removeRectangles
public void removeRectangles(double x, double y, double xlength, double ylength) Remove any portions of rectangles that intersect a rectangular area in the upper and/or lower grids.- Parameters:
x
- the lower-left X coordinate for the rectangular areay
- the lower-left Y coordinate for the rectangular areaxlength
- the length of the rectangular area in the X directionylength
- the length of the rectangular area in the Y direction
-
addHalfRectangle
public void addHalfRectangle(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset) Insert a half rectangle into the upper or lower grid, but not both.- Parameters:
x
- the lower-left X coordinate for the rectangley
- the lower-left Y coordinate for the rectanglelength
- the number of elements in the X and Y directions covered by this component.filledCorner
- the corner that lies within the filled region of this half rectanglezOffset
- the Z value of the upper-grid's rectangle relative to the base value for its grid
-
addHalfRectangle
public void addHalfRectangle(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset, boolean placeholder) Insert a half rectangle into the upper or lower grid, but not both, and specifying if the rectangle is a placeholder.- Parameters:
x
- the lower-left X coordinate for the rectangley
- the lower-left Y coordinate for the rectanglelength
- the number of elements in the X and Y directions covered by this component.filledCorner
- the corner that lies within the filled region of this half rectanglezOffset
- the Z value of the upper-grid's rectangle relative to the base value for its gridplaceholder
- true if this object is a placeholder; false if it is not.
-
addRectangle
public void addRectangle(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper) Add a rectangle to the upper or lower grid. For stepped grids that do not have both a lower and upper grid, the isUpper parameter must match the choice made in the constructor. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used. The default placeholder flags used by this method have the valuefalse
.- Parameters:
x
- the lower-left X coordinate for the rectangley
- the lower-left Y coordinate for the rectanglexlength
- the length of the rectangle in the X directionylength
- the length of the rectangle in the Y directionzOffset
- the Z value of the grid's rectangle relative to the base value for its gridisUpper
- true if the rectangle should be added to an upper grid; false if the rectangle should be added to the lower grid
-
addRectangle
public void addRectangle(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper, boolean placeholder) Add a rectangle to the upper or lower grid, specifying whether the rectangle is a placeholder. For stepped grids that do not have both a lower and upper grid, the isUpper parameter must match the choice made in the constructor. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used.- Parameters:
x
- the lower-left X coordinate for the rectangley
- the lower-left Y coordinate for the rectanglexlength
- the length of the rectangle in the X directionylength
- the length of the rectangle in the Y directionzOffset
- the Z value of the grid's rectangle relative to the base value for its gridisUpper
- true if the rectangle should be added to an upper grid; false if the rectangle should be added to the lower gridplaceholder
- true if the rectangle to be added is a placeholder; false otherwise
-
setMaxZSpacing
public void setMaxZSpacing(double spacing) Set the maximum spacing between vertices in the Z direction.This method is intended for cases where a model is configured with an instance of
Transform3D
, when that transform does not map straight lines to straight lines. In that case, one will typically configure a grid as collection of small rectangles. This method will ensure that the spacing between vertices is small in the Z direction as well.- Parameters:
spacing
- the maximum spacing; 0.0 or a negative value if there is none
-
hasMaxZSpacing
public boolean hasMaxZSpacing()Determine if this stepped grid has a maximum spacing in the Z direction.- Returns:
- true if a maximum spacing exists; false otherwise
-
getMaxZSpacing
public double getMaxZSpacing()Get the maximum spacing between vertices in the Z direction.- Returns:
- the maximum spacing; 0.0 if none is defined.
-
getXs
public double[] getXs()Get the X coordinates delimiting grid elements.- Returns:
- the X coordinates in ascending order.
-
getYs
public double[] getYs()Get the Y coordinates delimiting grid elements.- Returns:
- the Y coordinates in ascending order.
-
getIndexFromX
public int getIndexFromX(double x) For a given key get the index into the array thatgetXs()
would return.- Parameters:
x
- the key- Returns:
- the index; a negative value if x does not lie on the boundary between elements
-
getIndexFromY
public int getIndexFromY(double y) For a given key, get the index into the array thatgetYs()
would return.- Parameters:
y
- the key- Returns:
- the index; a negative value if y does not lie on the boundary between elements
-
create
Create a stepped grid and place it in the default model.- Returns:
- the stepped grid that was created
-
create
Create a stepped grid.- Parameters:
m3d
- the model to which the grid will be added- Returns:
- the stepped grid that was created
-