CameraProjectOperator Class
Projects a non-georeferenced image raster on the ground based on camera parameters.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class CameraProjectOperator : OperatorRemarks
A CameraProjectOperator takes a feature representing a photograph or video frame that is not orthorectified, and uses special attributes from the feature to georeference it.
The operator is only meant to be used in a 2D View, see CameraProjectOverlay to project images in 3D. The operator is not supported by the Software renderer; it is therefore not possible to have a CameraProjectOperator under a LayerRasterizeOperator since the Software renderer would be used during rasterization.
 |
Like any other feature in Carmenta Engine, the image feature from ObjectInput must have a Crs, but in this case the CRS just a convenient fiction: the feature will have a rectangular RasterGeometry with corners nominally expressed in this CRS, but those corner coordinates have no meaning and will be ignored by the CameraProjectOperator. However, the operator will assume that this CRS is used for the feature attributes that it will use to georeference the image.
The operator may be used for a photograph or for a video stream.
To display a video stream, you will need to code your own custom dataset that interprets the video format and generates raster features with the required attributes. There is a sample application that demonstrates this approach, see Projected Video Sample.
To display a static photograph, a custom dataset may still be best, but it should also be possible to store the image feature in a MemoryDataSet. If you use a MemoryDataSet, however, the fictional coordinates for the raster geometry corners are not completely arbitrary: since the ReadOperator trusts them, they must be chosen so that the fictional extent of the image covers at least the area of interest; that is, the area where the CameraProjectOperator will project the image. This will ensure that the ReadOperator will retrieve the image from the MemoryDataSet whenever the View.Area overlaps the area of interest. For example, you can let the fictional extent cover the whole world.
The operator can use two different methods to georeference the image.
It can take feature attributes that describe the position and orientation of the camera.
It can take feature attributes that give the georeferenced coordinates of the four corners of the image.
The two methods require different attributes to be set on the raster feature. The choice of method is done based on what attributes are present. If attributes for both methods are present, the camera mode will be selected.
Camera attributes
Attribute | Type | Description |
|---|---|---|
cameraX | double | The X coordinate of the camera, expressed in the CRS of the image feature. |
cameraY | double | The Y coordinate of the camera, expressed in the CRS of the image feature. |
cameraElevation | double | The elevation of the camera, in meters above mean sea level (MSL). |
cameraAzimuth | double | The azimuth of the camera, in degrees clockwise from true north. |
cameraPitch | double | The pitch of the camera, in degrees up from horizontal. |
cameraRoll | double | The roll of the camera, in degrees with positive values meaning camera starboard down. |
cameraVerticalFieldOfView | double | The vertical field of view (FOV) of the camera, expressed in degrees. |
cameraHorizontalFieldOfView | double | The horizontal field of view (FOV) of the camera, expressed in degrees. |
platformAzimuth | double | Optional The azimuth of the platform carrying the camera, in degrees clockwise from true north. |
platformPitch | double | Optional The pitch of the platform carrying the camera, in degrees up from horizontal. |
platformRoll | double | Optional The roll of the platform carrying the camera, in degrees with positive values meaning camera starboard down. |
The interpretation of the camera attributes will also depend on the MaxRange, which is an attribute variable that may be read from another image attribute, or which can be a constant defined in the configuration.
To georeference an image from camera parameters, the operator will construct the pyramid defined by the camera's position, orientation, field of view and max range, and will search for the intersection of this pyramid with the ground surface coming from the ElevationInput. Ideally, the four pyramid corners that are not the camera should be below ground, in which case the entire image will be projected to the ground. However, that may not be the case, either because the camera is oriented so that the upper part of the image displays the sky, or because the given max range was too short. If so, the operator can still project the lower part of the image onto the ground, provided that the two bottom image corners correspond to pyramid corners below ground. Otherwise, no output will be generated for the image.
The attributes for platform azimuth, pitch, and roll are optional. If these attributes are set, the meaning of the camera azimuth, pitch, and roll is changed to be the angles relative the carrying platform that the camera is attached to and the orientation of the platform is determined by these attributes. They are not mutually optional: all three need to be set or they are ignored.
If the operator does not find all required camera attributes, it will instead look for feature attributes that give the coordinates for the corners of the image on the ground:
Frame attributes
Attribute | Type | Description |
|---|---|---|
topLeftFrameX | double | The X coordinate matching the top left corner of the image. |
topLeftFrameY | double | The Y coordinate matching the top left corner of the image. |
topRightFrameX | double | The X coordinate matching the top right corner of the image. |
topRightFrameY | double | The Y coordinate matching the top right corner of the image. |
bottomRightFrameX | double | The X coordinate matching the bottom right corner of the image. |
bottomRightFrameY | double | The Y coordinate matching the bottom right corner of the image. |
bottomLeftFrameX | double | The X coordinate matching the bottom left corner of the image. |
bottomLeftFrameY | double | The Y coordinate matching the bottom left corner of the image. |
The operator will then stretch the image to fit the given quadrilateral, using one of two possible stretching methods. If all corners are less than 175°, a perspective transform is used - one could say that the operator figures out where the camera must have been. Otherwise, some corner must be very obtuse or even concave, in which case a perspective transform would not be practical; instead a simpler stretch is made by dividing the image by a diagonal and using an affine transform for each half.
Output features
From the input image, the operator will normally generate three output features:
A mesh feature that is textured by the image.
A line feature representing the outline of the image on the ground.
A point feature representing the center of the image on the ground.
Any incoming features that are not raster features will be passed on through the operator. To distinguish the outline feature and the center feature from other non-raster features that may pass through the operator, the outline feature will get the attribute projectedImageOutline = True, and the center feature will get the attribute projectedImageCenter = True.
The point feature for the image center will be generated only if the image center was successfully projected to the ground. So, if only the lower part of the image can be projected to the ground (see Camera attributes above), it is possible to get the mesh feature and the outline feature but no center point feature.
A visualizer is generated to visualize the projected image. If you use your own VisualizationOperator, for example to visualize the outline feature, set the mode property to Append so that the generated visualizer is not removed, which would be the default behavior.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
CameraProjectOperator
Platforms
Windows, Linux, Android
CameraProjectOperator Members
The CameraProjectOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| CameraProjectOperator | Initializes a new instance of the CameraProjectOperator class |
Properties
| Name | Description |
|---|---|
| Description | Gets or sets a short description of the operator. Inherited from Operator |
| DisplayName | Gets or sets a display name for the operator. Inherited from Operator |
| ElevationInput | Gets or sets the input operator from which elevation data is read. |
| IsDisposed | Gets a value that tells whether the current CameraProjectOperator has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the operator. Inherited from Operator |
| MaxRange | Gets or sets the maximal 3D distance from the camera, for which the image can be projected to the ground. |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current CameraProjectOperator represents. Inherited from EngineObject |
| ObjectInput | Gets or sets the input operator from which non-orthorectified image raster features are read. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from Operator |
| FlushCache | Marks the layer as flushed which will release cached resources during the next update. Inherited from Operator |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from Operator |
| GetFeatures | Overloaded. Gets features from the operator chain. Inherited from Operator |
| GetLocalizedDescription | Gets a localized version of the operator description in a specific language. Inherited from Operator |
| GetLocalizedDisplayName | Gets a localized version of the operator display name in a specific language. Inherited from Operator |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from Operator |
| GetRasterFeature | Overloaded. Gets raster features from the operator chain and merges them into a single raster. Inherited from Operator |
| HasLocalizedDescription | Checks if a localized version of the operator description is available in a specific language. Inherited from Operator |
| HasLocalizedDisplayName | Checks if a localized version of the operator display name is available in a specific language. Inherited from Operator |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from Operator |
| SetLocalizedDescription | Sets a operator description in a specific language. Inherited from Operator |
| SetLocalizedDisplayName | Sets a operator display name in a specific language. Inherited from Operator |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the operator, for a specific language. Inherited from Operator |