Skip to main content

Your first 3D building

Read this first
  • Make sure you completed the installation process, if you ran into issues try following the installation guide.
  • Did you already create an app template in one of the previous tasks? Then you can continue to implementing the 3D model.

Set up the app template​

When you start creating a new app the first thing you need to do is to create an app template. The required steps depend on the chosen installation method.

Would you like to watch a short video?

  1. Create a new folder for your app

    Add a new folder in your filesystem (e.g. C:\Users\<username>\viktor-apps\my-app) and open it in your code editor of choice

  1. In your terminal enter the following command and hit enter:

    viktor-cli create-app --app-type editor

    This will make all the necessary files in your app folder for you.

  2. Install the app and it's dependencies and start it in your development workspace by using the following command in the terminal:

    viktor-cli clean-start

    If all went well, your app is installed and running in your development workspace:

    INFO    :  __      __ __  __  __
    INFO    :  \ \    / / | | | |/ /
    INFO    :   \ \  / /  | | | ' /
    INFO    :    \ \/ /   | | |  <
    INFO    :     \  /    | | | . \
    INFO    :      \/     |_| |_|\_\
    INFO    :   _______   ____    _____
    INFO    :  |__   __| / __ \  |  __ \
    INFO    :     | |   | |  | | | |__) |
    INFO    :     | |   | |  | | |  _  /
    INFO    :     | |   | |__| | | | \ \
    INFO    :     |_|    \____/  |_|  \_\
    INFO    : VIKTOR connector vX.Y.Z
    INFO    : VIKTOR SDK vX.Y.Z
    INFO    : Connecting to platform...
    INFO    : Connection is established: <URL>  <---- here you can see your app
    INFO    : The connection can be closed using Ctrl+C
    INFO    : App is ready

    Do not close the terminal as this will break the connection with your app.

  3. Open your development workspace if you are not in it yet

    You can now navigate to the URL shown in the terminal (as highlighted above), and enter your Development workspace by clicking the open button.

Define the input fields​

Restarting your app
  • The app will update automatically after adding your code and saving the app.py file, as long as you don't close the terminal.
  • Did you close your code editor? Use viktor-cli start to start the app again. No need to run the install and clear commands.
  • Once your app is started you will be able to interact with it in your Development workspace

In this task you will learn how to create a 3D model in VIKTOR. At the end of this tutorial you will have created a parametric cylindrical building.

Open app.py, this is where we will place all the code for our app. First, add all the imports to the top of the file:

from viktor import ViktorController
from viktor.parametrization import ViktorParametrization, NumberField, Text

from viktor.geometry import CircularExtrusion, Group, Material, Color, Point, LinearPattern, Line
from viktor.views import GeometryView, GeometryResult

To make an app interactive, you can add inputs to the Parametrization class. Let's make sure to add a text to indicate that these are the inputs for our building. Add:

  1. A Text heading: "Building dimensions".
  2. A NumberField for the diameter with a minimum of 10 and a default of 20.
  3. Another NumberField for the number of floors, this can have a minimum of 3 and a default of 10.

If you feel comfortable programming this yourself, feel free to use the code below to check your code. Otherwise you can copy the lines from below. You only need to add the highlighted lines of code.

class Parametrization(ViktorParametrization):
    text_building = Text('## Building dimensions')
    building_diameter = NumberField('Building diameter', min=10, default=20)
    building_floors = NumberField('Number of floors', min=3, default=10)

As you can see each parameter in the Parametrization has a label. The NumberField has some more inputs available. This can help us constrain or even improve the user experience and prevent edge-cases from breaking the app! If you save the app (and make sure it is running in your terminal) and go to your development workspace, then you should be able to see the title and the two parameters appear.

Add the 3D model to your app​

Now that the inputs are in place, we can add the visualization. Visualizations are defined as methods on the Controller class. We begin by adding the standard template for any geometry view. You only need to add the highlighted lines of code.

class Controller(ViktorController):
    label = 'My Entity Type'
    parametrization = Parametrization

    @GeometryView("3D model", duration_guess=1, x_axis_to_right=True)
    def starter_guide_model(self, params, **kwargs):
        return GeometryResult(geometry=[])

Now we can fill the template with some features that we can see in the app. We create the geometry by using an CircularExtrusion from the VIKTOR SDK, we will use our diameter parameter to control the diameter of the extrusion and we will specify a line which the extrusion can follow. You only need to add or change the highlighted lines of code.

class Controller(ViktorController):
    label = 'My Entity Type'
    parametrization = Parametrization

    @GeometryView("3D model", duration_guess=1, x_axis_to_right=True)
    def starter_guide_model(self, params, **kwargs):
        floor_glass = CircularExtrusion(
            diameter=params.building_diameter,
            line=Line(Point(0, 0, 0), Point(0, 0, 2)),
        )
        return GeometryResult(geometry=[floor_glass])

The inputs you defined on the Parametrization are passed to the GeometryView method with the params argument. For example, the building diameter is used as input for the diameter of the CircularExtrusion by referencing its variable name params.building_diameter.

If you save the app and refresh the page of the app in the browser you should see this:

Feel free to change one of the inputs to see the effect on the geometry.

Now that we have this short cylinder for the floor, we also want to have a similar but thinner slab to represent the facade of the building. We will need to move (the mathematical term is translate) the slab to be on top of the windows. Furthermore, materials are assigned with different colors such that the building looks much better in the interface.

Then we can define the floor as the combination of layers (glass + facade), using a Group object, and then we will simply duplicate this using the LinearPattern to form the building! You only need to add or change the highlighted lines of code.

class Controller(ViktorController):
    label = 'My Entity Type'
    parametrization = Parametrization

    @GeometryView("3D model", duration_guess=1, x_axis_to_right=True)
    def starter_guide_model(self, params, **kwargs):
        floor_glass = CircularExtrusion(
            diameter=params.building_diameter,
            line=Line(Point(0, 0, 0), Point(0, 0, 2)),
            material=Material("Glass", color=Color(150, 150, 255))
        )
        floor_facade = CircularExtrusion(
            diameter=params.building_diameter+1,
            line=Line(Point(0, 0, 0), Point(0, 0, 1)),
            material=Material("Concrete", color=Color(200, 200, 200))
        )
        floor_facade.translate((0, 0, 2))
        floor = Group([floor_glass, floor_facade])
        building = LinearPattern(floor, direction=[0, 0, 1], number_of_elements=params.building_floors, spacing=3)
        return GeometryResult(geometry=building)

And that's it! Let's check the browser for the full model. Test the app and make sure that the parameters make the changes to the 3D building.

You now know the basics of making and adding 3D models to your VIKTOR app.

Continue the next section or come back tomorrow to spread the workload!