c3a.hc.caas
Advanced tools
This library is not an officially supported part of HOOPS Communicator and provided as-is.
For questions/feedback please send an email to guido@techsoft3d.com or post in our forum. For a 60 day trial of the HOOPS Web Platform go to https://www.techsoft3d.com/products/hoops/web-platform.
To quickly test out CaaS, follow the steps below.
{
"hc-caas": {
"license": "HOOPS_COMMUNICATOR_LICENSE_KEY",
"runStreamingServer": false,
"modelManager": {
"runStreamingManager": false
},
"conversionServer": {
"converterpath": "PATH_TO_COMMUNICATOR_DIRECTORY/authoring/converter/bin/win64",
}
}
}
{
"hc-caas": {
"license": "HOOPS_COMMUNICATOR_LICENSE_KEY",
"conversionServer": {
"converterpath": "PATH_TO_COMMUNICATOR_DIRECTORY/authoring/converter/bin/win64",
},
"streamingServer": {
"scserverpath": "PATH_TO_COMMUNICATOR_DIRECTORY/server/bin/win64",
},
"storage": {
"type": "S3", //...or ABS for Azure Blob Storage
"destination": "mydestination", // Either S3 Bucket or Azure Container name
"ABS": {
"connectionString": "YOUR AZURE CONNECTION STRING"
}
}
}
}
To simplify the integration of CaaS into your own application, we have created a separate module that provides a simple API for all CaaS functionality. Please see here for more information: CAAS-API module
We have created a Docker container and an AMI for AWS that can be used to quickly deploy CaaS. Please see here for more information: Docker Container and AMI
A basic demo application that uses the API directly from JS and which can be used for testing CaaS locally and exploring the REST API usage can be found here: Basic Demo Github Link. This demo is the perfect starting point for understanding how to use CaaS in your own application via its REST API.
Please see here for the User Management Module that includes a more advanced demo application: User Management Module.
{
"mongodbURI": "mongodb://127.0.0.1:27017/conversions",
"accessPassword": "",
"workingDirectory": "caasTemp",
"serviceIP": "localhost",
"port": "3001",
"runModelManager": true,
"runConversionServer": true,
"runStreamingServer": true,
"license": "",
"licenseFile": "",
"fullErrorReporting": false,
"region": "",
"requireAccessKey": false,
"determineGeoFromRequest": false,
"conversionServer": {
"name" : "",
"converterpath": "",
"HEimportexportpath": "",
"HEInstallPath": "",
"maxConversions": 4,
"polling": false,
"allowSCSConversion": true,
"imageServicePort": "3002",
"priority": 0,
},
"modelManager": {
"listen": true,
"purgeFiles": false,
"runStreamingManager": true,
},
"streamingServer": {
"streamingRegion": "",
"scserverpath": "",
"renderType": "client",
"useEGL": false,
"maxStreamingSessions": 10,
"useSymLink": false,
"publicURL": "",
"publicPort": "",
"startPort": 3006,
"listenPort": 3200,
"name" : "",
"priority": 0,
},
"storage": {
"type": "filesystem",
"destination": "",
"copyDestinations": [],
"replicate": false,
"externalReplicate": false,
"ABS": {
"connectionString":"",
"accountName": ""
}
},
"localCache": {
"directory": "",
"maxSize": 0
}
}
CaaS requires a running mongoDB session. If you are planning to run multiple connected CaaS instances, you need to provide a common database session to all connected instances. We recommend MongoDB Atlas for that purpose but you can of course run your own database server. For more information see the links below. After the database is running you need to provide the connection string in the mongodbURI field. For security reasons it is recommended that you omit the username and password (if any) and instead provide those in the environment variables "DB_USERNAME" and "DB_PASSWORD".
[MongoDB Local Install] (https://www.mongodb.com/try/download/community)
[MongoDB Atlas] (https://www.mongodb.com/atlas/database)
Create a folder for temporary data and provide the path in the workingDirectory field.
Specify desired port. In production, CaaS is meant to run behind a firewall and should not be accessible from the web directly but you need to still ensure that the port is accessible if CaaS runs on a different machine from the main application.
Set runConversionServer to true if you want to run the conversion queue on this machine. As long as the machines running the conversion queue are sharing the same database session, and storage you can run an unlimited number of instances in parallel.
Set runModelManager to true if you want to run the CaaS Rest API frontend on this machine. The frontend provides the REST API endpoints for the conversion queue and streaming servers. It is possible to have multiple active frontends, all connected to the same storage and database. This could be a desirable configuration in a multi-region setup.
If you enabled the conversion queue (runConversionServer:true) you need to provide the path to the directory containing the converter executable of the HOOPS Communicator package/installation. You also need to provide a valid license for HOOPS Communicator.
If the conversion queue is running on a different machine from the server you need to specify the ip address and port of the queue here that is accessible from the server.
By default CaaS will assign conversion jobs to all registered conversion queue servers based on their available capacity. If polling is set to true the conversion queue will poll for a newly available job every few seconds. In this case a conversion queue server does not need to be registered with the main server.
If you are uploading SCS or SCZ files, CAAS will use a separate module in order to generate PNG's for those file types. See here for more information. You can specify the port this module uses for its internal server here.
If you are running CaaS as a node module and use the API directly you can optionally turn off all REST API endpoints. In this case your code needs to handle file uploads and other actions.
If you are planning to use S3 or Azure Blob Storage for storing the converted models you need to set the "storage.type" field to "S3" or "ABS" and provide a valid bucket/container name in the "storage.destination" field. For S3 you also need to make sure AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID is set, either via environment variables or through a config file. (see AWS Credentials). For ABS you need to provide either a connection string or your authorized account name (see here). If you are using a network of multiple conversion queue instances, you need to specify a bucket/container that is accessible to all instances.
If you are planning to support SCZ model streaming, you need to provide the path to ts3d_sc_server.exe. Each parallel streaming session on the same machine will run on separate consecutive ports, the range specified by startPort and maxStreamingSession, which are proxied from listenPort.
Run CaaS via npm start
npx ts3d.hc.caas
npm install ts3d.hc.caas
Follow steps 2 - 14 from above.
In the startup module of your application, add the following code to initialize the conversion server:
const conversionserver = require('ts3d.hc.caas');
conversionserver.start();
While it is easy to setup CaaS to run on a single machine, it is often desirable to scale the system to multiple machines, in particular for CAD conversions. This can be done by running multiple instances of CaaS on different machines. Each instance can be configured to run the conversion queue, the streaming server or both. As long as all instances are connected to the same database and storage, they will be able to share the load.
[todo: add diagram, configuration examples]
To improve performance, it might be desirable to deploy multiple instances of CaaS in different regions. There are a few things to consider when doing this:
If "hc-caas.cache.maxSize" is > 0, CaaS will cache a model when it is first accessed. This value is in MB and represents the maximum allowed model cache on disk. You can also specify the directory for the cache, otherwise it will be inside the workingDirectory folder. Caching can greatly improve performance, in particular for large SCZ or SCS files.
It might be desirable to run the streaming service via a proxy, so that all requested are processed via port 80 or 443. An example of such a setup can be found in proxy.js.
[todo: more details]
[todo]
[todo]
[todo]
** OUTDATED - NEEDS UPDATE. PLEASE REFER TO THE CAAS-API module FOR THE MOST UP TO DATE API **
Uploads a new CAD file and places it on the conversion queue.
let form = new FormData();
form.append('file', fs.createReadStream("myfile.stp"));
let res = await fetch(caasURI + '/caas_api/upload', { method: 'POST', body: form,headers: {'CS-API-Arg': JSON.stringify({webhook:"http://localhost:3000/caas_api/webhook"})}});
let data = await res.json();
CS-API-Arg:
{
webhook: "http://localhost:3000/caas_api/webhook",
startPath: "micro_engine/_micro engine.CATProduct",
conversionCommandLine:["--output_scs","","--output_png","","background_color","0,0,0","--output_step",""],
storageID: "c79dd99e-cbbd-4b6d-ba43-15986b1adc14",
processShattered:false,
skipConversion:false,
}
webhook - The ip address to call when the conversion is complete. If not provided polling is required to check the conversion status.
startPath - If a zip file is uploaded this is the relative path within the zip file to the main assembly file.
conversionCommandLine - The command line arguments to pass to converter. This will replace the default command line that exports scs and png files (on a white background).
storageID - If an existing storageID is provided, the uploaded file will be stored alongside the original file and no conversion will be performed.
processShattered - If set to true, a shattered version of the CAD assembly will be generated.
skipConversion - If set to true, the uploaded file will not be converted.
ID of newly created item
{"storageID":"c79dd99e-cbbd-4b6d-ba43-15986b1adc14"}
Retrieves data about a conversion item.
let res = await fetch(caasURI + '/caas_api/data/c79dd99e-cbbd-4b6d-ba43-15986b1adc14');
As specified in URL string:
Information about the requested item.
{
name: "landinggearmainshaftwithpmi_fullpmi.catpart",
startPath: "",
conversionState: "SUCCESS",
updated: "2022-05-29T12:52:02.787Z",
created: "2022-05-29T12:51:55.697Z",
webhook: "http://localhost:3000/caas_api/webhook",
files: [
"landinggearmainshaftwithpmi_fullpmi.catpart.png",
"landinggearmainshaftwithpmi_fullpmi.catpart.scs",
],
}
Retrieves a file from the conversion server.
let res = await fetch(caasURI + '/caas_api/file/c79dd99e-cbbd-4b6d-ba43-15986b1adc14/scs');
let buffer = await res.arrayBuffer();
...
As specified in URL string:
Binary Data
Retrieves the file that was uploaded to the conversion server.
let res = await fetch(caasURI + '/caas_api/original/c79dd99e-cbbd-4b6d-ba43-15986b1adc14');
let buffer = await res.arrayBuffer();
...
As specified in URL string:
Binary Data
Reconverts an existing conversion item.
let res = await fetch(caasURI + '/caas_api/reconvert/c79dd99e-cbbd-4b6d-ba43-15986b1adc1', { method: 'put', headers: {'CS-API-Arg': JSON.stringify({conversionCommandLine:["--output_step",""] })}});
...
As specified in URL string:
CS-API-Arg:
{
startPath: "micro_engine/_micro engine.CATProduct",
conversionCommandLine:["--output_scs","","--output_png","","background_color","0,0,0","--output_step",""],
processShattered: false,
}
startPath - If a zip file is uploaded this is the relative path within the zip file to the main assembly file.
conversionCommandLine - The command line arguments to pass to converter. This will replace the default command line that exports scs and png files (on a white background).
processShattered - If set to true, a shattered version of the CAD assembly will be generated.
NONE
Deletes a conversion item including all converted data.
let res = await fetch(caasURI + '/caas_api/delete/c79dd99e-cbbd-4b6d-ba43-15986b1adc1', { method: 'put'});
...
As specified in URL string:
NONE
Retrieves a list of all conversion items available on the conversion server.
let res = await fetch(caasURI + '/caas_api/items');
...
NONE
JSON Array of available conversion items and all their data.
Retrieves the time any of the items on the conversion server were last updated (or deleted).
let res = await fetch(caasURI + '/caas_api/items');
...
NONE
JSON containing last updated time
{lastUpdated: '2022-05-29T14:27:03.001Z'}
Retrieves an upload token for directly uploading a file to S3 storage. After receiving the token and uploading the file directly from the client, api/reconvert should be called to start the conversion process.
let res = await fetch(caasURI + '/caas_api/uploadToken', {headers: {'CS-API-Arg': JSON.stringify({webhook:"http://localhost:3000/caas_api/webhook"})}});
CS-API-Arg:
{
webhook: "http://localhost:3000/caas_api/webhook"
}
webhook - The ip address to call when the conversion is complete. If not provided polling is required to check the conversion status.
JSON containing signed request URL and storageID
{ token: signedRequestURLforS3, storageID: c79dd99e-cbbd-4b6d-ba43-15986b1adc14 };
Retrieves a download token for directly downloading a file from S3 storage.
let res = await fetch(caasURI + '/caas_api/downloadToken/c79dd99e-cbbd-4b6d-ba43-15986b1adc1/scs');
As specified in URL string:
JSON containing signed request URL
{ token: signedRequestURLforS3 };
Retrieves a shattered part for a conversion item converted with the processShattered argument.
let res = await fetch(caasURI + '/caas_api/shattered/c79dd99e-cbbd-4b6d-ba43-15986b1adc14/part.scs');
let buffer = await res.arrayBuffer();
...
As specified in URL string:
Binary Data
Retrieves the shattered XML file for a conversion item converted with the processShattered argument.
let res = await fetch(caasURI + '/caas_api/shatteredXML/c79dd99e-cbbd-4b6d-ba43-15986b1adc14');
let shatteredData = await res.text();
...
As specified in URL string:
XML data
Request a new streaming session
let res = await fetch(caasURI + '/caas_api/streamingSession');
let data = await res.json();
viewer = new Communicator.WebViewer({
containerId: "viewerContainer",
endpointUri: 'ws://' + data.serverurl + ":" + data.port + '?token=' + data.sessionid,
model: "_empty",
rendererType: Communicator.RendererType.Client
});
...
None
JSON Object
{ serverurl: url of streaming server,
port: port of streaming server,
sessionid: session id for streaming session };
Makes an scz file available for streaming
await fetch(caasURI + '/caas_api/enableStreamAccess/' + sessionid, { method: 'put', headers: { 'items': JSON.stringify([modelid]) } });
...
As specified in URL string:
CS-API-Arg:
items - Array of model ids to make available for streaming.
None
Retrieves CaaS Version String
None
CaaS Version
FAQs
* Account Support * Various Updates and Enhancements
The npm package c3a.hc.caas receives a total of 0 weekly downloads. As such, c3a.hc.caas popularity was classified as not popular.
We found that c3a.hc.caas demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.