Cadmai.Poi3dPlugin.WinFormsControl 1.1.0

Poi3D Nuget Packages

Introduction

The Poi3D Nuget packages include .Net Framework controls which are used to embed the Poi3D collaboration portal into Windows based client applications (more information about the Poi3D portal can be found at https://poi3d.com).

These Poi3D controls allow documents, whether in the form of 2D files or 3D models, to be viewed and supplemented with attachments.

For example, annotations can be added to PDF or image files, or sensor data, such as from home automation, can be displayed. In the 3D domain, surfaces can be designed, instructions defined, and bill of materials created. The software also supports Augmented Reality (AR) and Virtual Reality (VR), allowing viewer positions to be saved.

All defined attachments can be stored parallel to the document, ensuring that the original document remains unchanged.

The Poi3D controls provides their functionality both locally on the computer and via the web. This is achieved by embedding a web browser, which displays the portal version of Poi3D, within the Poi3D controls, allowing communication between the two. The corresponding portal URL can be set via a property, allowing self-hosted Poi3D portals to be integrated into the client.

The Poi3D controls also support the conversion of 3D standard formats like JT, STEP, STL, OBJ, GLB, or GLTF into a format which can be displayed in the web browser.

Functional information

Local file operations

In local mode, the user is not logged into the portal. While they use the functions of the embedded web portal, all attachments are passed to the client application and are not sent to the server.

Web operations

When the user is logged in and a local file is open, it can be saved in the portal and shared with other portal users. This is done through the save dialog, which is accessed via the "Save to Portal" command in the portal menu.

Once the document is saved in the portal, it can then be made available to other users via workgroups. Additionally, further files can be attached to the document. If attachments to portal documents which were sent from the client application are created or modified, these changes will be passed to the client application as well.

Programming information

Environment

The Poi3D controls use the .Net Framework 4.7.2 and the C++ runtime 14.0 under 64 bit. The runtime can be downloaded from https://aka.ms/vs/17/release/vc_redist.x64.exe

Downloads

The controls can be downloaded from https://www.nuget.org (Cadmai.Poi3dPlugin.WinFormsControl or Cadmai.Poi3dPlugin.WpfControl)

Embedding

After the Nuget package is installed, the embedded Poi3dPortalControl can be dragged into a Windows/WPF Form.

Communication

The communication between the client and the Poi3D control is established by using methods provided from the Poi3D control and reacting to events sent by the Poi3D control. To handle events from the portal just add an even handler to the Poi3dControlEvent provided by the Poi3D control.

How to initialize the portal

public Form1()
{
  InitializeComponent();

  poi3dPortalControl.PortalUrl = "https://demo.mypoi3d.com/Poi3dViewer.html";
  // default is https://poi3d-portal.com/Poi3dViewer.html

  poi3dPortalControl.PortalColor = Poi3dPortalColor.Light;
  poi3dPortalControl.PortalLanguage = Poi3dPortalLanguage.English;
  poi3dPortalControl.OpenPortalWebSite();
}

How to convert/open a local file

private void openLocalFileMenuItem_Click(object sender, EventArgs e)
{
  OpenFileDialog openFileDialog = new OpenFileDialog();

  openFileDialog.Filter = "All Files|*.wpm;*.obj;*.stl;*.3ds;*.glb;*.gltf;*.stp;*.step;*.jt;*.3dxml;*.jpg;*.png;*.tif;*.bmp;*.svg;*.gif;*.pdf|" +
    "3D Mesh Files (*.wpm;*.obj;*.stl;*.3ds;*.glb;*.gltf)|*.wpm;*.obj;*.stl;*.3ds;*.glb;*.gltf|" +
    "3D CAD Files (*.stp;*.step;*.jt;*.3dxml)|*.stp;*.step;*.jt;*.3dxml|" +
    "Image Files (*.jpg;*.png;*.tif;*.bmp;*.svg;*.gif)|*.jpg;*.png;*.tif;*.bmp;*.svg;*.gif|" +
    "2D Documents (*.pdf)|*.pdf";

  openFileDialog.FilterIndex = 1;
  openFileDialog.Multiselect = false;
  openFileDialog.RestoreDirectory = true;

  var success = openFileDialog.ShowDialog();

  if (success == DialogResult.OK) //if (success == true) for WPF
  {
    string inputFileName = openFileDialog.FileName;
    string extension = System.IO.Path.GetExtension(inputFileName).ToLower();

    switch (extension)
    {
      case ".obj":
      case ".stl":
      case ".3ds":
      case ".glb":
      case ".gltf":
      case ".3dxml":
      case ".jt":
      case ".step":
      case ".stp":
        poi3dPortalControl.Convert3dModel(inputFileName);
        break;
      case ".wpm":
      case ".jpg":
      case ".png":
      case ".bmp":
      case ".svg":
      case ".gif":
      case ".tif":
      case ".pdf":
        poi3dPortalControl.OpenLeftDocumentFromFile(inputFileName, "");
        break;
    }
  }
}

How to receive information from the portal

private async void poi3dPortalControl_Poi3dControlEvent(object sender, Poi3dControlEventArgs args)
{
  switch (args.EventType)
  {
    case Poi3dPortalEvents.AnnotationsSaved:
      string annotations = await poi3dPortalControl.GetDocumentAnnotations();
      //-> save the annotations
      break;
    case Poi3dPortalEvents.AnnotationsRequested:
      //-> read and send the annotations
      string annotationString = "[]";
      Poi3dMessage result = await poi3dPortalControl.SetDocumentAnnotations(annotationString);
      break;
    case Poi3dPortalEvents.ModelConverted:
      string fullFileNameToLoad = args.Info;
      //-> open the model
      poi3dPortalControl.OpenLeftDocumentFromFile(fullFileNameToLoad, "");
      break;
  }
}

Properties

The following properties are published:

• PortalUrl: Gets or sets the URL where the portal is located (default: https://poi3d-portal.com/Poi3dViewer.html)
• ZoomFactor: Gets or sets the zoom factor for the browser (default: 1.0)
• PortalColor: Gets or sets the portal color (default: Poi3dPortalColor.Light)
• PortalLanguage: Gets or sets the portal language (default: Poi3dPortalLanguage.English)

Methods

The following portal methods are available:

• Convert3dModel: Converts a 3d model to the wpm format and stores it in the directory of the input file
• GetDocIdsFromLoadedDocument: Queries the document id's of the currenty loaded document
• GetDocumentAnnotations: Queries the annotations which are attached to the document
• GetDocumentAttributes: Queries the attributes which are attached to the document
• GetDocumentBomStructures: Queries the BOM's which are attached to the document
• GetDocumentFileAttachments: Queries the file attachments which are attached to the document
• GetDocumentInstructions: Queries the instructions which are attached to the document
• GetDocumentMaterialSets: Queries the material sets which are attached to the document
• GetDocumentSensors: Queries the sensor configurations which are attached to the document
• GetDocumentViewLocations: Queries the viewer locations which are attached to the document
• LoginUser: Logs the given user into the portal
• LogoffUser: Logs the current user out of the portal
• OpenLeftDocumentFromFile: Opens a document in the control browser
• OpenLeftDocumentFromUrl:: Opens a document in the control browser
• OpenPortalWebSite: Opens the portal URL in the control browser
• ReloadPortal: Clears the browser cache and reloads the portal URL in the control browser
• SaveDocumentAttachementsToPortal: Saves the document attachments from the currently loaded document back to the Poi3D portal
• SetDocumentAnnotations: Attaches annotations to the document
• SetDocumentAttributes:: Attaches attributes to the document
• SetDocumentBomStructures: Attaches BOM's to the document
• SetDocumentFileAttachments: Attaches file attachments to the document
• SetDocumentInstructions: Attaches instructions to the document
• SetDocumentMaterialSets: Attaches material sets to the document
• SetDocumentSensors: Attaches sensor configurations to the document
• SetDocumentViewLocations: Attaches viewer locations to the document
• ShowPortalInfo: Shows a status text in the control browser with the given message
• ShowPortalMessage: Shows a message dialog in the control browser with the given message

Events

The following events are sent from the control:

• AnnotationsRequested: Annotations requested
• AnnotationsSaved: Annotations saved by menu click
• BomStructuresRequested: BOMs requested
• BomStructuresSaved: BOMs saved by menu click
• ClientEnvironmentError: Sent if the client environment does not meet the plugins requirements
• DocAttributesSaved: Document attributes saved by menu click
• DocAttributesRequested: Document attributes requested
• DocumentLoaded: Document loaded
• DocumentSaved: Document saved in portal
• FileAttached: Send if the user attaches a file to a document
• FileAttachmentsRequested: File attachments requested
• FileAttachmentsSaved: File attachments saved by menu click
• InstructionsRequested: Instructions requested
• InstructionsSaved: Instructions saved by menu click
• LoginSuccess: Sent if a user is logged in. The alias name can be found in the Poi3dControlEventArgs.Info property
• LogoffSuccess: Sent if a user is logged off. The alias name can be found in the Poi3dControlEventArgs.Info property
• MaterialSetsRequested: Material sets requested
• MaterialSetsSaved: ,Material sets saved by menu click
• MethodCallError:: Sent if an error occured in an async call
• ModelConversionError: Sent if a 3d model coild not be converted. The error text can be found in the Poi3dControlEventArgs.Info property
• ModelConverted: Sent if a 3d model was converted to the wpm format. The wpm file name can be found in the Poi3dControlEventArgs.Info property
• PortalLoaded: Portal loaded
• PortalVersionError: Sent if the portal version does not meet the plugins requirements
• SensorsRequested: Sensor configuration requested
• SensorsSaved: Sensor configuration saved by menu click
• ViewLocationsRequested: Viewer locations requested
• ViewLocationsSaved: Viewer locations saved by menu click

Misc

To avoid DPI switching for Windows Forms applications (e.g. after model conversion) just use the DpiAware.manifest for your application which is inserted into the development project.

Licensing

Poi3D controls, licensed under the MIT license, use external libraries like the Microsoft WebView2 control or OpenCASCADE libraries for 3D model conversion. The license information is stored in the docs folder of the package.

As a default, the Poi3D portal https://poi3d-portal.com is referenced, which can be used freely. If you want to use or host your own Poi3D portal instance please find more information at https://mypoi3d.com/Hosting.html

Disclaimer

Copyright CADMAI Software GmbH. All rights reserved.

The redistributor / user does not have the right to change, translate, back-develop, decompile or disassemble the software.

Redistributions must retain the above copyright notice, this list of conditions and the following disclaimer.

Neither the name of CADMAI Software GmbH nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE