Skip to main content
Version: 1.0

Import data with CLI

Now that you've rendered your first scene, try importing your own 3D data using the Vertex command-line interface (CLI). The CLI makes Vertex API calls on your behalf, simplifying typical operations into single commands.

note
The following instructions assume:

Install the CLI​

  1. Install the CLI with either npm or Yarn. If you need help, here's a third-party video for setting up Node.js and npm.

    npm install --global @vertexvis/cli

  2. Verify it's working by accessing help.

    # Help for the CLI as a whole
    vertex --help

    # Help for an individual command
    vertex configure --help

    # Help for a topic
    vertex scenes --help

    # Help for a command within a topic
    vertex scenes:get --help

CLI authentication​

  1. Have your Vertex client ID and secret ready so that the CLI can authenticate Vertex API calls on your behalf.

    note
    Your Vertex client secret is sensitive and must be kept secure at all times. You should never include it in client-side web applications.

  2. Run vertex configure and follow the prompts.

    vertex configure
    note

    Some customers use a different base API path than the default (https://platform.vertexvis.com). In this case, add the --basePath option to all commands, e.g., vertex configure --basePath [YOUR_BASE_PATH].

    After you follow the prompts, the command creates ~/.config/@vertexvis/cli/config.json on macOS/Linux and %LOCALAPPDATA%\@vertexvis\cli\config.json on Windows with your credentials. When you run additional commands, the CLI uses these to authenticate API calls.

Keep your client ID and secret handy; you'll use it in the following guide as well.

Import data​

  1. To import 3D data in one of Vertex's supported formats, create a JSON file containing a list of scene items. Multiple CLI commands use this JSON file to build requests for the API.

    note

    If you don't have 3D data handy, download a prepared model from our 3D database to follow along.

    To import an entire assembly, you may need to take an additional step to prepare it for Vertex.

    Below is a simple example of a JSON file with the required parameters specified. For a complete list and explanation of each parameter, see the type definition.

    vertex-valve.json
    [
      {
        "indexMetadata": true,
        "source": {
          "fileName": "[YOUR_PATH_TO_3D_DATA_FILE_INCLUDING_FILE_EXTENSION]",
          "suppliedPartId": "vertex-valve",
          "suppliedRevisionId": "1"
        }
      }
    ]

  2. Next, run create-parts with the path to this JSON file as an argument. create-parts uploads the 3D data, translates it into 3D geometry, and creates parts in Vertex's Parts Library. Vertex's Parts Library is a repository of your team's or organization's parts, each with references to geometry and optional metadata. As we'll see later in this guide, you can use combinations of these parts to build scenes.

    vertex create-parts [YOUR_PATH_TO_JSON_FILE]

Render scenes​

  1. With the parts now in Vertex's Parts Library, run create-scene to create a scene and add the root part as a scene item to that scene. This command prints the created scene ID.

    vertex create-scene --name [YOUR_SCENE_NAME] [YOUR_PATH_TO_JSON_FILE]

  2. To render the scene, run the scenes:render command and include the --viewer flag along with the scene ID from the previous step. The --viewer flag creates an HTML file using Vertex's Viewer component similar to the one you wrote in the Render your first scene guide. It then opens this file in your browser so you can interact with it.

    vertex scenes:render --viewer [YOUR_SCENE_ID]

Keep your scene ID handy; you'll use it in the following guide as well.

Wrapping up​

Congratulations! You've imported your own 3D data into Vertex and interacted with it using our Viewer component. To recap the concepts learned so far:

  • Vertex's command-line interface (CLI) makes Vertex API calls on your behalf, simplifying typical operations into single commands.
  • Vertex's Parts Library is a repository of your team's or organization's parts. You can build scenes using any combination of these parts.

We explained a few commands in this guide, but for a complete list of CLI commands and their options, check out the vertex-cli README.