CogSurfaceFXTool Class

Cognex VisionPro 9.5

Class that represents the top-level SurfaceFX tool. The SurfaceFX tool accepts four two-dimensional images as input. Each image must show the same physical scene. But each image must be acquired under a different illumination condition :

The first image must be lit from the right.
The second image must be lit from the bottom.
The third image must be lit from the left.
The fourth image must be lit from the top.

The SurfaceFX tool uses these images to estimate the three - dimensional shape of the physical scene. The generated 3D surface cannot be "seen" by our customers – it is entirely internal – but, it is the(only) data used to generate the tool's final output image. The output image is a single 8-bit grey-level image which shows the flat portions of the 3D surface as uniform grey and highlights the highly-curved sections of the surface as either white (if the surface curvature is concave-down) or black (if the surface curvature is concave-up). This image can be used to visualize 3D surface features such as bumps, dents, scratches, engraving and etchings. T this image can also be passed to other VisionPro tools, like Blob, to analyze the location and size of these highly-curved 3D surface features.

Inheritance Hierarchy

System Object
  System MarshalByRefObject
    System.ComponentModel Component
      Cognex.VisionPro.Implementation CogComponentBase
        Cognex.VisionPro.Implementation CogSerializableComponentBase
          Cognex.VisionPro.Implementation CogSerializableChangedEventComponentBase
            Cognex.VisionPro.Implementation CogToolBase
              Cognex.VisionPro.SurfaceFX CogSurfaceFXTool

Namespace: Cognex.VisionPro.SurfaceFX
Assembly: Cognex.VisionPro.SurfaceFX (in Cognex.VisionPro.SurfaceFX.dll) Version: 69.0.0.0

Syntax

C++

Copy to Clipboard Print

[SerializableAttribute]
public class CogSurfaceFXTool : CogToolBase

[SerializableAttribute]
public class CogSurfaceFXTool : CogToolBase

<SerializableAttribute>
Public Class CogSurfaceFXTool 
	Inherits CogToolBase

<SerializableAttribute>
Public Class CogSurfaceFXTool 
	Inherits CogToolBase

[SerializableAttribute]
public ref class CogSurfaceFXTool : public CogToolBase

[SerializableAttribute]
public ref class CogSurfaceFXTool : public CogToolBase

The CogSurfaceFXTool type exposes the following members.

Constructors

	Name	Description
	CogSurfaceFXTool	Constructs a default CogSurfaceFXTool object. This new tool contains a default set of run params.
	CogSurfaceFXTool(CogSurfaceFXTool)	Constructs a deep copy of the supplied CogSurfaceFXTool object.
	CogSurfaceFXTool(SerializationInfo, StreamingContext)	Serialization constructor for CogSurfaceFXTool object.

Top

Methods

	Name	Description
	CheckRunConditions	Check for run conditions including data binding. (Inherited from CogToolBase.)
	CheckRunConditionsNoThrow	Check for run conditions including data binding, returning an exception for the first problem encountered. (Inherited from CogToolBase.)
	Clone	Returns a deep copy of this CogSurfaceFXTool object. (Overrides CogToolBase Clone .)
	CreateCurrentRecord	Creates a new set of records that represents the tool's current state. (Inherited from CogToolBase.)
	CreateLastRunRecord	Creates a new set of records that represents the tool's last-run state. (Inherited from CogToolBase.)
	CreateObjRef	Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
	Dispose	Releases all resources used by the Component. (Inherited from Component.)
	Dispose(Boolean)	(Overrides Component Dispose(Boolean).)
	Equals	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Releases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection. (Inherited from Component.)
	GetAttributes	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetClassName	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetComponentName	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetConverter	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetDefaultEvent	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetDefaultProperty	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetEditor	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetEvents	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetEvents( Attribute )	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetLifetimeService	Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
	GetObjectData	Serializer for CogSurfaceFXTool object. (Overrides CogSerializableComponentBase GetObjectData(SerializationInfo, StreamingContext).)
	GetProperties	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetProperties( Attribute )	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetPropertyOwner	Implements the corresponding member of the ICustomTypeDescriptor interface. May be overridden in derived classes to provide custom type information. (Inherited from CogComponentBase.)
	GetService	Returns an object that represents a service provided by the Component or by its Container. (Inherited from Component.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	InitializeLifetimeService	Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
	InternalCreateCurrentRecord	(Overrides CogToolBase InternalCreateCurrentRecord(ICogRecord, Int32).)
	InternalCreateLastRunRecord	(Overrides CogToolBase InternalCreateLastRunRecord(ICogRecord, Int32, Int32).)
	InternalRun	(Overrides CogToolBase InternalRun(String ).)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	MemberwiseClone(Boolean)	Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
	OnChanged(Int64)	This method should be called internally whenever the object's state may have changed. (Inherited from CogSerializableChangedEventComponentBase.)
	OnChanged(CogChangedEventArgs)	This method may be called internally whenever a derived object's state may have changed and the derived object expresses this change via a derived CogChangedEventArgs class. (Inherited from CogSerializableChangedEventComponentBase.)
	OnDeserialization	(Inherited from CogToolBase.)
	OnRan	Raises the Ran event. (Inherited from CogToolBase.)
	OnRunning	Raises the Running event. (Inherited from CogToolBase.)
	ResumeAndRaiseChangedEvent	Re-enables raising of the Changed event after SuspendChangedEvent has been called, and raises the Changed event if the ChangedEventSuspended count is reduced to zero and any changes were made while events were suspended. Must be called once for each call to SuspendChangedEvent. (Inherited from CogSerializableChangedEventComponentBase.)
	Run	Runs the tool. This method is guaranteed to not throw an exception. Any exception generated in the course of running the tool will be caught and packaged in the tool's RunStatus.Exception. Should this occur, the tool's RunStatus.Result will be set to Error and its RunStatus.Message will reference the message that accompanied the exception. It is the user's responsibility to examine the tool's RunStatus after calling Run. (Inherited from CogToolBase.)
	SetRunStatus	Cognex Internal use only. (Inherited from CogToolBase.)
	SuspendChangedEvent	Temporarily suspends the raising of the Changed event. May be called more than once, and a corresponding call to ResumeAndRaiseChangedEvent must be made for each call to SuspendChangedEvent. (Inherited from CogSerializableChangedEventComponentBase.)
	ToString	Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component.)

Top

Fields

	Name	Description
	CurrentRecordEnable_	Gets or sets the flags specifying the records to include based on the tool's current state. The derived class exposes this as a strongly- typed enum property. (Inherited from CogToolBase.)
	LastRunLastRunRecordDiagEnable_	Gets or sets the flags specifying the records to create during the next invocation of the Run method. (Inherited from CogToolBase.)
	LastRunRecordDiagEnable_	Gets or sets the flags specifying the diagnostics records to include based on the tool's last-run state. The derived class exposes this as a strongly-typed enum property. (Inherited from CogToolBase.)
	LastRunRecordEnable_	Gets or sets the flags specifying the records to include based on the tool's last-run state. The derived class exposes this as a strongly- typed enum property. (Inherited from CogToolBase.)
	ProcessingTimeAdjustment_	Gets or sets the amount to offset reported tool processing time. (Inherited from CogToolBase.)
	SfCurrentRecordEnable	This bit will be set in the EventArgs of a Changed event every time the value returned by CurrentRecordEnable may have changed.
	SfInputVisionData	This bit will be set in the EventArgs of a Changed event every time the value returned by InputVisionData may have changed.
	SfLastRunRecordDiagEnable	This bit will be set in the EventArgs of a Changed event every time the value returned by LastRunRecordDiagEnable may have changed.
	SfLastRunRecordEnable	This bit will be set in the EventArgs of a Changed event every time the value returned by LastRunRecordEnable may have changed.
	SfLitFromBottomInputImage	This bit will be set in the EventArgs of a Changed event every time the LitFromBottomInputImage may have changed.
	SfLitFromLeftInputImage	This bit will be set in the EventArgs of a Changed event every time the LitFromLeftInputImage may have changed.
	SfLitFromRightInputImage	This bit will be set in the EventArgs of a Changed event every time the LitFromRightInputImage may have changed.
	SfLitFromTopInputImage	This bit will be set in the EventArgs of a Changed event every time the LitFromTopInputImage may have changed.
	SfNextSf
	SfOutputImage	This bit will be set in the EventArgs of a Changed event every time the output image may have changed.
	SfRegion	This bit will be set in the EventArgs of a Changed event every time the value returned by Region may have changed.
	SfRunParams	This bit will be set in the EventArgs of a Changed event every time the value returned by RunParams may have changed.

Top

Properties

	Name	Description
	CanRaiseEvents	Gets a value indicating whether the component can raise an event. (Inherited from Component.)
	ChangedEventSuspended	If nonzero, indicates that the raising of the Changed event has been suspended. This value is incremented when SuspendChangedEvent is called and decremented when ResumeAndRaiseChangedEvent is called. (Inherited from CogSerializableChangedEventComponentBase.)
	Container	Gets the IContainer that contains the Component. (Inherited from Component.)
	CurrentRecordEnable	Enable the creation of graphical tool records by bitwise ORing the desired values from CogSurfaceFXCurrentRecordConstants.
	DataBindings	Gets the data bindings for the tool. (Inherited from CogToolBase.)
	DesignMode	Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component.)
	Events	Gets the list of event handlers that are attached to this Component. (Inherited from Component.)
	FailOnInvalidDataBinding	Specifies that the Run method is to fail if executed while one or more data bindings are invalid. (Inherited from CogToolBase.)
	HasChanged	(Inherited from CogSerializableChangedEventComponentBase.)
	InputVisionData	Gets or Sets the input vision data container. When a CogSurfaceFXTool is first constructed, the InputVisionData property is pre - populated with a CogVisionDataContainer that has four "null" images. As a convenience, the keys that identify these images are pre - defined to be "LitFromRight", "LitFromBottom", etc. If the user hates these keys they can replace the entire CogVisionDataContainer with a new one that has completely different keys. When a user replaces the InputVisionData property, the CogSurfaceFXTool will immediately verify that the container has four items, with keys that are suitable as names in a coordinate space tree. Each item must be an ICogImage, or null. We only insist that each image is a CogImage8Grey at runtime. Replacing the InputVisionData container fires a Changed event for that property, and also for the individual image properties if they are different. At runtime, the CogSurfaceFX operator will check that the InputVisionData property contains exactly four images of type CogImage8Grey. It will assume that the first image in the container was lit from the right, the second image was lit from below, etc. The key strings that are associated with each image will only be used as a space name in the merged coordinate space tree of the output image, if they are used at all.
	LastRunRecordDiagEnable	Enable the creation of graphical tool records by bitwise ORing the desired values from CogSurfaceFXLastRunRecordDiagConstants.
	LastRunRecordEnable	Enable the creation of graphical tool records by bitwise ORing the desired values from CogSurfaceFXLastRunRecordConstants.
	LitFromBottomInputImage	Gets or sets the Lit from bottom input image that will be used at run time. This property sets the value of the second record in the InputVisionData container.
	LitFromLeftInputImage	Gets or sets the Lit from left input image that will be used at run time. This property sets the value of the third record in the InputVisionData container.
	LitFromRightInputImage	Gets or sets the Lit from right input image that will be used at run time. This property sets the value of the first record in the InputVisionData container.
	LitFromTopInputImage	Gets or sets the Lit from top input image that will be used at run time. This property sets the value of the fourth record in the InputVisionData container.
	Name	Gets or sets a user-supplied name for the tool. (Inherited from CogToolBase.)
	OutputImage	Gets the OutputImage from the last run of the tool.
	Region	Gets or sets the region. The region bounding box specifies the portion of each image to be processed. The output image size is based on the region bounding box size.
	RunParams	Gets or sets the parameters to be used when this SurfaceFX tool is run.
	RunStatus	Gets general information about the last call to the tool's Run function. Note that serious errors that occur within the tool's Run method may only be detected by examining the RunStatus after calling Run. It is the user's responsibility to examine the tool's RunStatus after calling Run. (Inherited from CogToolBase.)
	Site	Gets or sets the ISite of the Component. (Inherited from Component.)
	StateFlags	Returns the complete set of state flags supported on this object. The flags may be indexed by name as shown in the following C# code snippet: if (changedObject.StateFlags["Color"] & eventArgs.StateFlags) { ... } (Inherited from CogSerializableChangedEventComponentBase.)
	UserData	Gets a CogDictionary object that can be used to store application-specific information. (Inherited from CogToolBase.)

Top

Events

	Name	Description
	Changed	This event is raised when one or more parts of the object's state may have changed. (Inherited from CogSerializableChangedEventComponentBase.)
	Disposed	Occurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)
	Ran	Event that is raised at the end of the tool's Run method. (Inherited from CogToolBase.)
	Running	Event that is raised at the start of the tool's Run method. (Inherited from CogToolBase.)

Top

Remarks

Limitations:

Requires four images whose pixels are the same size (relative to the physical scene), but are acquired using different illumination.
Requires customers to align the input images, using fixturing, if there is any motion between them.
Does not account for rotation between the images.
Does not account for sub-pixel shifts between images.
Will produce poor output – and not an error – if the motion between the input images is excessive, or contains rotation.