Nodemap

<< Click to Display Table of Contents >>

Navigation:  CVB with GenICam > CVB Driver Structure >

Nodemap

 

A Nodemap displayed in the Property Grid is a part of the Transport Layer and therefore available for all  GenICam compliant cameras.

Nodemaps are based on the acquisition hardware *.xml file and structured in different ports :

 

DevicePort

 

 

DeviceTLPort

 

 

DataStreamPort

 

 

FactoryPort

 

 

InterfacePort

 

 

TLPort

 

If the device has no *.xml file in its memory a "Nodemap unavailable" message is returned when the device is opened.

Be aware that setting a correct XML file for the device is a precondition, if there are problems, refer trouble shooting section.

 

For Parameter Reference refer GenICam Standard, SFNC (Standard Features Naming Convention) part.

 

Get access to the Nodemaps over GenICam Browser:

NodeMap

 

DevicePort

This is the port which contains the Nodemap for the device (remote device).

It is the normal Nodemap for all device features and is used by default and is returned with the CV GenApi function NMHGetNodeMap().

 

Programmatically it is referenced in the header file (iDC_GenICam.h) over the enumeration DC_PARAM_GENICAM with:

DC_DEVICE_PORT_NODEMAP = 0x00000500

 

Nodemap_DevicePort

 

DeviceTLPort

This is the port which contains the Nodemap for the device module of the GenTL.

The device module represents the GenTL Producers’ proxy for one physical remote device.

The responsibility of the device module is to enable the communication with the remote device and to enumerate and instantiate data stream modules.

The device module also presents signaling- and module configuration capabilities.

 

Programmatically it is referenced in the header file (iDC_GenICam.h) over the enumeration DC_PARAM_GENICAM with:

DC_DEVICE_NODEMAP = 0x00000400 

Nodemap_DeviceTLPort

 

DataStreamPort

This is the port which contains the nodemap for the Data Stream module.

A single (image) data stream from the device is represented by the Data Stream module.

The purpose of this module is to provide the acquisition engine and to maintain the internal buffer pool.

Beside that the Data Stream module also presents Signaling and module configuration capabilities.

 

Programmatically it is referenced in the header file (iDC_GenICam.h) over the enumeration DC_PARAM_GENICAM with:

DC_DATASTREAM_NODEMAP = 0x00000600

 

Nodemap_DtatStreamPort

 

UpdateStatistics

This is a command which refreshes the more expensive statistics (those without a polling icon).

 

NumBuffersQueued

Number of buffers which, at a given point in time, can take new data. Only queued buffers can take new image data. Buffers which are not queued are basically locked.

In CVB, before a G2Grab starts all announced buffers are also queued for acquisition. So until the first image starts the NumBuffersQueued = NumBuffersAnnounced.

While the first image is transferred the number of queued images is one less than at the start.

After the first image finished until the first call to G2Wait the NumBuffersQueued = NumBuffersAnnounced-1 and the pending frames = 1.

After G2Wait and before the second image starts NumBuffersQueued = NumBuffersAnnounced-1, delivered buffers=1, pending frames=0. And so on.

 

NumBuffersAnnounced

These are the buffers known to the GenTL which can hold image data. Only known buffers can be queued (and thus filled with incoming frame data).

This has direct influence on the amount of memory allocated by the driver to hold image data.

 

NumBuffersAwaitDelivery

The number of buffers which have been filled with image data and which are not yet collected by (delivered to) the application (e.g. via G2Wait or ImageSnappedEvent).

 

NumBuffersInIncompleteList

Number of buffers which have been started to fill but are not yet done.

In case this (internal) incomplete list is full the buffer will, depending on the configuration of the driver, delivered as corrupt buffer to the host application or discarded .

In other words this counter indicates that a new frame arrived but the old one is not complete yet due to missing packets. It is only updated when packet resend is enabled.

 

NumFramesLostQueueUnderrun

This is a lost frame counter indicating that an new incoming frame from a camera could not be filled because no buffers where queued.

This normally means that the processing is too slow and cannot keep up with the frame-rate of the camera.

 

NumFramesCorruptOnDelivery

Number of images which were corrupt (not complete) when delivered through G2Wait. A corrupt delivered image cannot/will not be completed after delivery.

 

NumFramesStarted

The number of buffers taken from the input queue. This means the number of frames the GenTL tries to fill with incoming data.

 

FramesCorrupt

Number of images which were corrupt on arrival in the host no matter if or if not resend requests have been issued.

This setting indicates if something is wrong with the transmission. In case the user wants to discard corrupt images he needs to configure his video interface/TL accordingly.

A corrupt image is an image which in the first run did not arrive properly.

This includes also images which for example had missing packets and which have been completed later on using resend requests.

So a corrupt image may not be corrupt on delivery because the transport mechanisms underneath corrected the failure.

 

NumPacketsReceived

This is related to GigE and indicates the number of data packets (not frames) received on the GigE Vision streaming channel. received.

 

NumResends

This is related to GigE and indicates the number of resend requests issued by the host. If this number increases it indicates that something is wrong with the data transmission.

Possible reasons may be: Settings of the network card, CPU-load on the host, cable/switch problems, bandwidth problems on the Link

(only incremented if missing packets occur and packet resend is enabled).

Following examples show how to access features within a CVB program.

 

Sample Code in C++

// gets the data stream node map from the driver

NODEMAP GetDataStreamNodeMap(IMG hDriver)

{

  NODEMAP hNodeMap = 0;

  size_t size = sizeof(NODEMAP);

  DCBinaryCommand(hDriver,

    DeviceCtrlCmd(DC_DATASTREAM_NODEMAP, DC_GET),

    NULL, 0,

    &hNodeMap, size);

  return hNodeMap;

}

 

// Retrieve the value for the Number of Lost Frames 

void LostFrames(IMG hDriver)

{

  if (NODEMAP hStreamNodeMap = GetDataStreamNodeMap(hDriver))

  {

    NODE hNumFramesUnderrun = NULL;

    NMGetNode(hStreamNodeMap, "Cust::Stat_NumFramesLostQueueUnderrun", hNumFramesUnderrun);

    __int64 iLost = 0;

    NGetAsInteger(hNumFramesUnderrun, iLost);

    ReleaseObject(hNumFramesUnderrun);

    ReleaseObject(hStreamNodeMap);

  }

}

 

// Enables packet resend

void EnablePacketResend(IMG hDriver)

{

  if (NODEMAP hStreamNodeMap = GetDataStreamNodeMap(hDriver))

  {

    NODE hEnablePacketResend = 0;

    if (NMGetNode(hStreamNodeMap, "EnablePacketResend", hEnablePacketResend) >= 0)

    {

      if (NSetAsBoolean(hEnablePacketResend, true) >= 0)

        cout << "Successfully enabled packet resend." << endl;

      else

        cout << "Enable Packet Resend: Error enabling feature!" << endl;

      ReleaseObject(hEnablePacketResend);

    }

    else

    {

      cout << "Enable Packet Resend: Error retrieving node!" << endl;

    }

    ReleaseObject(hStreamNodeMap);

  }

  else

  {

    cout << "Enable Packet Resend: Error retrieving stream node map!" << endl;

  }

}

 

// Discards corrupt frames

void DiscardCorruptFrames(IMG hDriver)

{

  if (NODEMAP hStreamNodeMap = GetDataStreamNodeMap(hDriver))

  {

    NODE hPassCorruptFrames = 0;

    if (NMGetNode(hStreamNodeMap, "PassCorruptFrames", hPassCorruptFrames) >= 0)

    {

      if (NSetAsBoolean(hPassCorruptFrames, false) >= 0)

        cout << "Successfully disabled passing corrupt frames." << endl;

      else

        cout << "Pass Corrupt Frames: Error disabling feature!" << endl;

      ReleaseObject(hPassCorruptFrames);

    }

    else

    {

      cout << "Pass Corrupt Frames: Error retrieving node!" << endl;

    }

    ReleaseObject(hStreamNodeMap);

  }

  else

  {

    cout << "Pass Corrupt Frames: Error retrieving stream node map!" << endl;

  }

}

 

FactoryPort

This is the port which contains the Nodemap for the Factory which represents the GenICam.vin driver.

Programmatically it is referenced in the header file (iDC_GenICam.h) over the enumeration DC_PARAM_GENICAM with:

DC_FACTORY_NODEMAP = 0x00000100

 

Nodemap_FactoryPort

 

InterfacePort

This is the port which contains the Nodemap for the interface module.

An interface module represents one physical interface in the system.

For Ethernet based Transport Layer technologies this would be a Network Interface Card (NIC), for a Camera Link based implementation this would be one frame grabber board.

The enumeration and instantiation of available devices on this interface is the main role of this module.

The interface module also presents signaling and module configuration capabilities.

 

Programmatically it is referenced in the header file (iDC_GenICam.h) over the enumeration DC_PARAM_GENICAM with:

DC_INTERFACE_NODEMAP = 0x00000300

 

Nodemap_InterfacePort

 

C# Code Example

using System;

 

namespace NodeMapExample

{

  class Program

  {

    static void Main(string[] args)

    {

      using (var interfaceNodeMap = GetDriverInterfaceNodeMap(IntPtr.Zero))

      {

        // access the nodemap

        // add code to access the nodemap

      }

    }

 

    public static Cvb.SharedNodeMap GetDriverInterfaceNodeMap(Cvb.Image.IMG driver)

    {

      return GetDriverNodeMap(driver, DC_INTERFACE_NODEMAP);

    }

 

    public static unsafe Cvb.SharedNodeMap GetDriverNodeMap(Cvb.Image.IMG driver, int id)

    {

      IntPtr nodeMapHandle = IntPtr.Zero;

      int cmd = Cvb.Driver.IDeviceControl.DeviceCtrlCmd(id, Cvb.Driver.IDeviceControl.DC_OPERATION.GET);

      IntPtr handleSize = (IntPtr)IntPtr.Size;

      int result = Cvb.Driver.IDeviceControl.DCBinaryCommand(driver, cmd, IntPtr.Zero, IntPtr.Zero, new IntPtr(&nodeMapHandle), ref handleSize);

      if (result < 0)

        return null;

      else

        return new Cvb.SharedNodeMap(handle: nodeMapHandle, share: false);

    }

  }

}

 

 

TLPort

This is the port which contains the Nodemap for the system module.

For every GenTL Consumer the system module as the root of the hierarchy is the entry point to a GenTL Producer software driver.

It represents the whole system (not global, just the whole system of the GenTL Producer driver) on the host side from the GenTL libraries point of view.

The main task of the system module is to enumerate and instantiate available interfaces covered by the implementation.

The system module also provides signaling capability and configuration of the module's internal functionality.

 

Programmatically it is referenced in the header file (iDC_GenICam.h) over the enumeration DC_PARAM_GENICAM with:

DC_TL_NODEMAP = 0x00000200

 

Nodemap_TLPort