LinePolygonConcepts - GermaniumWeb

Lines & Polygons

1 Introduction
2 Line Strings
3 Polygons
4 Invalid Polygons
5 Using incompatible Geometry & GeometryStyle
6 References

Introduction

Other than point placemarks, you can also create line string placemarks and polygon placemarks.

This article shows you how to use line string placemarks and polygon placemarks. It assumes that you are familiar with the concept of placemarks introduced in the Placemarks article.

Line Strings

A line string is a set of connected line segments. You can use it to mark paths. Here is how you can create a line string:

Create a placemark.
Assign LineStringGeometry to the placemark.
Add vertices to the LineStringGeometry.
Customize line string appearance using LineStyle. The properties you can customize are:
- line color,
- line pattern,
- line pattern scale,
- line width, and
- animation mode.

Source: lines & polygons example, function CreateLineString()

// Create a placemark & set its name
var placemark = germ.CreatePlacemark("Path to level 2");
germ.AddPlacemark(placemark);
 
// Assign LineStringGeometry to the placemark
var linestringGeom = germ.CreateLineStringGeometry();	// create a LineStringGeometry object
placemark.SetGeometry(linestringGeom);			// assign it to the placemark
 
// Add vertices to the LineStringGeometry
linestringGeom.AppendVertex(germ.CreateVector3( 5.52, 0.00, -13.65));
linestringGeom.AppendVertex(germ.CreateVector3( 5.22, 0.00, -18.00));
linestringGeom.AppendVertex(germ.CreateVector3(-8.68, 0.00, -18.00));
linestringGeom.AppendVertex(germ.CreateVector3(-8.68, 0.00, -31.00));
linestringGeom.AppendVertex(germ.CreateVector3(-0.65, 0.00, -31.00));
linestringGeom.AppendVertex(germ.CreateVector3(-0.65, 0.00, -25.66));
linestringGeom.AppendVertex(germ.CreateVector3(-0.65, 2.67, -21.50));
linestringGeom.AppendVertex(germ.CreateVector3( 0.82, 2.67, -21.50));
linestringGeom.AppendVertex(germ.CreateVector3( 0.82, 4.20, -24.22));
linestringGeom.AppendVertex(germ.CreateVector3( 0.82, 4.20, -26.22));
linestringGeom.AppendVertex(germ.CreateVector3(-0.55, 4.20, -26.22));
linestringGeom.AppendVertex(germ.CreateVector3(-0.55, 4.20, -32.98));
 
// Customize line string appearance using LineStyle
var lineStyle = germ.CreateLineStyle();			// create a LineStyle object
lineStyle.SetLineColor("00DDA1");			// customize LineStyle
lineStyle.SetLineWidth(4);
lineStyle.SetLinePattern(Germanium.GeometryStyle.LinePattern.Dashed3);
lineStyle.SetAnimationMode(Germanium.LineStyle.Animation.Forward);
var styleSet = germ.CreateStyleSet();			// create a StyleSet object
styleSet.SetGeometryStyle(lineStyle);			// apply LineStyle to StyleSet
placemark.SetStyleSet(styleSet);			// apply StyleSet to Placemark
 
// Hide higher levels so we can see the line string
var building = germ.GetBuildingByIndex(0);
var block = building.GetBlockByBBLId("OFFICE");
var level = block.GetLevelByBBLId("L01");
level.HideLevelsAbove();

Tip: Refer to Coordinate System article to learn how GermaniumWeb represents position.

Polygons

You can mark an area using a polygon. Here is how you can create a flat, 2D polygon:

Create a placemark.
Assign PolygonGeometry to the placemark.
Add vertices to the PolygonGeometry.
Change appearance using PolygonStyle. The properties you can change are:
- fill color,
- fill image,
- fill mode,
- outline color,
- outline pattern,
- outline width, and
- smooth threshold.

Source: lines & polygons example, function CreatePolygon()

// Create a placemark
var placemark = germ.CreatePlacemark("Our office");
placemark.SetContent("After you reach level 2, please proceed here.");
germ.AddPlacemark(placemark);
 
// Assign PolygonGeometry to the placemark
var polygonGeom = germ.CreatePolygonGeometry();	// create a PolygonGeometry object
placemark.SetGeometry(polygonGeom);		// assign it to the placemark
 
// Add vertices to the PolygonGeometry
polygonGeom.SetPosition(16, 8, -16.4);
polygonGeom.AppendVertex(germ.CreateVector2(  0.0,   0.0));
polygonGeom.AppendVertex(germ.CreateVector2(-27.6,   0.0));
polygonGeom.AppendVertex(germ.CreateVector2(-27.6,  -6.8));
polygonGeom.AppendVertex(germ.CreateVector2(-29.2,  -6.8));
polygonGeom.AppendVertex(germ.CreateVector2(-29.2, -11.4));
polygonGeom.AppendVertex(germ.CreateVector2(-13.2, -11.4));
polygonGeom.AppendVertex(germ.CreateVector2(-13.2, -13.9));
polygonGeom.AppendVertex(germ.CreateVector2(  0.0, -13.9));
 
// Customize polygon appearance using PolygonStyle
var polygonStyle = germ.CreatePolygonStyle();	// create a PolygonStyle object
polygonStyle.SetFillColor("46EBFF99");		// customize PolygonStyle
polygonStyle.SetOutlineColor("0087A4");
polygonStyle.SetOutlineWidth(2);
polygonStyle.SetFillMode(Germanium.PolygonStyle.FillAndOutline);
var styleSet = germ.CreateStyleSet();		// create a StyleSet object
styleSet.SetGeometryStyle(polygonStyle);	// apply PolygonStyle to StyleSet
placemark.SetStyleSet(styleSet);		// apply StyleSet to Placemark
 
// Show level "L02" & hide levels above it
var building = germ.GetBuildingByIndex(0);
var block = building.GetBlockByBBLId("OFFICE");
var level = block.GetLevelByBBLId("L02");
level.Show();
level.HideLevelsAbove();

You can extrude a polygon to create a simple volume. Extruding a PolygonGeometry does not increase its vertex count.

Source: lines & polygons example, function CreateExtrudedPolygon()

// Create a placemark
var placemark = germ.CreatePlacemark("Meeting area");
placemark.SetContent("We will discuss using one of the tables in this area.");
germ.AddPlacemark(placemark);
 
// Assign PolygonGeometry to the placemark
var polygonGeom = germ.CreatePolygonGeometry();	// create a PolygonGeometry object
placemark.SetGeometry(polygonGeom);		// assign it to the placemark
 
// Add vertices to the PolygonGeometry
polygonGeom.SetPosition(4.0, 4.21, -3.8);
polygonGeom.AppendVertex(germ.CreateVector2(0, 0));
polygonGeom.AppendVertex(germ.CreateVector2(6, 0));
polygonGeom.AppendVertex(germ.CreateVector2(6, 5.2));
polygonGeom.AppendVertex(germ.CreateVector2(0, 5.2));
 
// Extrude the polygonpolygonGeom.SetExtrusionHeight(3); 
// Customize polygon appearance using PolygonStyle
var polygonStyle = germ.CreatePolygonStyle();	// create a PolygonStyle object
polygonStyle.SetFillColor("46AEFF99");		// customize PolygonStyle
polygonStyle.SetOutlineColor("93DAFF");
polygonStyle.SetOutlineWidth(2);
polygonStyle.SetFillMode(Germanium.PolygonStyle.FillAndOutline);
var styleSet = germ.CreateStyleSet();		// create a StyleSet object
styleSet.SetGeometryStyle(polygonStyle);	// apply PolygonStyle to StyleSet
placemark.SetStyleSet(styleSet);		// apply StyleSet to Placemark
 
// Show level "L02" & hide levels above it
var building = germ.GetBuildingByIndex(0);
var block = building.GetBlockByBBLId("OFFICE");
var level = block.GetLevelByBBLId("L02");
level.Show();
level.HideLevelsAbove();

Using 3D vertex functions

Since API 1.4, you create a PolygonGeometry by specifying 3D vertices instead of UV vertices. You can keep appending 3D vertices by calling Append3DVertex().

Source: lines & polygons example, function CreatePolygon_Append3DVertex()

// Create a placemark
var placemark = germ.CreatePlacemark("Created using Append3DVertex()");
placemark.SetMoreInfoUrl("http://www.germanium3d.com/static/code/api/index.php?content=files/Placemark-js.html@PolygonGeometry.Append3DVertex");
germ.AddPlacemark(placemark);
 
// Assign PolygonGeometry to the placemark
var polygonGeom = germ.CreatePolygonGeometry();
placemark.SetGeometry(polygonGeom);
 
// Add vertices to the PolygonGeometry
polygonGeom.Append3DVertex(10, 0.5, 10);polygonGeom.Append3DVertex(-5, 0.5, 10);polygonGeom.Append3DVertex(-5, 0.5, -5);polygonGeom.Append3DVertex(10, 0.5, -5); 
// Customize polygon appearance using PolygonStyle
var polygonStyle = germ.CreatePolygonStyle();
polygonStyle.SetFillColor("FF46EB99");			// use red fill color
polygonStyle.SetOutlineColor("A40087");
polygonStyle.SetOutlineWidth(2);
polygonStyle.SetFillMode(Germanium.PolygonStyle.FillAndOutline);
var styleSet = germ.CreateStyleSet();
styleSet.SetGeometryStyle(polygonStyle);
placemark.SetStyleSet(styleSet);

Alternatively, you can set all 3D vertices at one go by calling Set3DVertices().

Source: lines & polygons example, function CreatePolygon_Set3DVertices()

// Create a placemark
var placemark = germ.CreatePlacemark("Created using Set3DVertices()");
placemark.SetMoreInfoUrl("http://www.germanium3d.com/static/code/api/index.php?content=files/Placemark-js.html@PolygonGeometry.Set3DVertices");
germ.AddPlacemark(placemark);
 
// Assign PolygonGeometry to the placemark
var polygonGeom = germ.CreatePolygonGeometry();
placemark.SetGeometry(polygonGeom);
 
// Add vertices to the PolygonGeometry
polygonGeom.Set3DVertices([	germ.CreateVector3(10, 10.5, 10),	germ.CreateVector3(-5, 10.5, 10),	germ.CreateVector3(-5, 10.5, -5),	germ.CreateVector3(10, 10.5, -5)	]); 
// Customize polygon appearance using PolygonStyle
var polygonStyle = germ.CreatePolygonStyle();
polygonStyle.SetFillColor("FF840099");			// use orange fill color
polygonStyle.SetOutlineColor("D85800");
polygonStyle.SetOutlineWidth(2);
polygonStyle.SetFillMode(Germanium.PolygonStyle.FillAndOutline);
var styleSet = germ.CreateStyleSet();
styleSet.SetGeometryStyle(polygonStyle);
placemark.SetStyleSet(styleSet);

Using fill image functions

Beginning with API 1.5, you can fill a polygon using an image. Doing so allows you to use polygons to represent content filled objects such as signages, storefronts, or advertising billboards.

Company Logo using a textured polygon

Changing the fill image

Source: lines & polygons example, function CreatePolygon_SetFillImage()

// Create a placemark
var placemark = germ.CreatePlacemark("Reception");
placemark.SetContent("Welcome to our office!");
germ.AddPlacemark(placemark);
 
// Assign PolygonGeometry to the placemark
var polygonGeom = germ.CreatePolygonGeometry();
placemark.SetGeometry(polygonGeom);
 
// Add vertices to the PolygonGeometry		
polygonGeom.Append3DVertex(3.62, 1.9, -20.217);
polygonGeom.Append3DVertex(6.52, 1.9, -20.217);
polygonGeom.Append3DVertex(6.52, 2.9, -20.217);
polygonGeom.Append3DVertex(3.62, 2.9, -20.217);
 
// Customize polygon appearance using PolygonStyle
var polygonStyle = germ.CreatePolygonStyle();
var image = germ.CreateImage("imgs/CompanyLogo01.png");
polygonStyle.SetFillImage(image);
var styleSet = germ.CreateStyleSet();styleSet.SetGeometryStyle(polygonStyle);placemark.SetStyleSet(styleSet);

Fill image tiling

In addition to specifying the image, you can also offset and tile the image on the polygon.

To create repeating patterns using the same image on a polygon, you can use the SetFillImageTilingFactor function to tile the image in the (u, v) directions independently.

No tiling

2 x 2 tile

Source: lines & polygons example, function TexturePolygon_ToggleTile()

polygonStyle.SetFillImageTilingFactor(2, 2);

Fill image offset

You can also modify the position of the image on the polygon using SetFillImageTilingOffset.

No Offset

0.5 x 0.5 offset

Source: lines & polygons example, function TexturePolygon_ToggleOffset()

polygonStyle.SetFillImageTilingOffset(0.5, 0.5);

Orienting the fill image

The fill image is oriented according to the polygon's Up vector. Typically, PolygonGeometry.Append3DVertex() and PolygonGeometry.Set3DVertices() sets the Up vector to be (0, 0, -1) for horizontal polygons and (0, 1, 0) for vertical polygons.

You can query a polygon's Up vector using PolygonGeometry.GetUpVector:

var upVector = pmark.GetGeometry().GetUpVector();

If the default orientation of the fill image is not oriented according to your needs, you may rotate the fill image around the polygon's Normal vector:

Source: lines & polygons example, function TexturePolygon_RotateFillImage()

var count = polyGeom.GetNumberOfVertices();
 
// Rotate vertices around local origin, i.e. the normal in world-space
var theta = Germanium.DegreeToRadian(angle);
var sin = Math.sin(theta);
var cos = Math.cos(theta);
 
var i=0, vtx;
for (i=0; i<count; ++i) {
  vtx = poly.GetVertex(i);
  polyGeom.ReplaceVertex(i,
  vtx.GetX() * cos - vtx.GetY() * sin,
  vtx.GetX() * sin + vtx.GetY() * cos);
}
polyGeom.RotateAroundNormalVector(-theta);

Note: The fill image may stretch or shrink to fit the polygon as it is rotated.

Scene lighting

Also added in API 1.5 is the option to control whether a polygon will be rendered with the same real-time lighting as the buildings in the 3D scene.

TV texture rendered with scene lighting

TV texture rendered without scene lighting

Source: lines & polygons example, function TexturePolygon_ToggleSceneLighting()

polygonStyle.SetUseSceneLighting(false);

Note: Typically, a textured polygon will look brighter when UseSceneLighting is disabled for the polygon.

Note: UseSceneLighting is also applicable to polygons without fill images. When disabled, the polygon will be purely colored with its fill color.

Invalid Polygons

You may find a polygon appear unshaded, like in the image on the right, even though you set its style to be shaded. This means that the polygon is invalid.

A polygon is NOT valid if:

it has fewer than 3 vertices (note that extruding a PolygonGeometry does not increase its vertex count),
it has an edge which doubles back on its neighboring edge, forming a zero degree angle at the shared vertex, or
any two of its edges intersect each other.

You can check if a polygon is valid using PolygonGeometry.IsValid().

Using incompatible Geometry & GeometryStyle

If a placemark has incompatible geometry and geometry style, the geometry determines the appearance of the placemark. For example, if a placemark has a PolygonGeometry object and its StyleSet contains a LineStyle object, the placemark will appear as a polygon with default polygon style.

See Placemark Appearance section in the API documentation for further details.

References

Retrieved from "http://www.germanium3d.com/code/LinePolygonConcepts"

This page has been accessed 435 times. This page was last modified on 9 June 2011, at 07:08.

Contents