Welcome to Helix Toolkit’s documentation!¶

Note

The documentation is under construction. Please contribute!

Helix Toolkit is a 3D library for .NET

Content¶

Introduction¶

Helix Toolkit is an open source 3D library that is licensed under the MIT license. The MIT license is very permissive and permits use in proprietary software.

The library is based on .NET and is currently focusing on the WPF platform.

The goal has been to make it easy to work with 3D in WPF, and also provide features that are not included in the standard WPF 3D visual model.

Background¶

Helix Toolkit was started in 2009.

Features¶

Note

This section is under construction. Please contribute!

Portable code¶

coming

WPF¶

3D viewport control that supports mouse and touch interaction
<todo> add more info

WPF+SharpDX¶

3D viewport control that supports mouse and touch interaction
<todo> add more info

License¶

Helix Toolkit is licensed under the MIT license. This is the shortest and probably broadest of all the popular open-source licenses. Its terms are very loose and more permissive than most other licenses. It is also compatible with GPL.

The license can be found in the LICENSE file that is located in the root folder of the repository:

The MIT License (MIT)

Copyright (c) 2012 Helix TOolkit contributors

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The license is explained in a short guide to open source licenses:

You can use, copy and modify the software however you want. No one can prevent you from using it on any project, from copying it however many times you want and in whatever format you like, or from changing it however you want.
You can give the software away for free or sell it. You have no restrictions on how to distribute it.
The only restriction is that it be accompanied by the license agreement.

The MIT License is the least restrictive license out there. It basically says that anyone can do whatever they want with the licensed material, as long as it is accompanied by the license.

Authors¶

Information about the copyright holders is found in the AUTHORS file.

Contributors¶

Information about the contributors is found in the CONTRIBUTORS file.

Getting Support¶

Community Support¶

Helix TOolkit has a small community that may help you out if you have questions. If you can’t find your answer in the documentation, you can...

Ask your question on the forum. This is a good idea if you have multiple questions or a question that might have a more subjective answer (e.g., “recommendations” sorts of things).
You can also try StackOverflow. Be sure to use the helix-3d-toolkit tag in your question.

Commercial Support¶

We are not aware of anyone offering commercial support

If you would like your company listed here, please let us know.

Frequently asked questions¶

Note

This section is under construction. Please contribute!

See also the FAQ section at http://forum.helix-toolkit.org.

Where is the source code?¶

The source code can be found at GitHub: https://github.com/helix-toolkit/helix-toolkit.

Where can I find examples?¶

You should get the source code and build one of the Visual Studio solution files. These solution includes the examples!

Glossary¶

Note

This section is under construction. Please contribute!

The goal of this page is to help keep documentation, discussions, and APIs consistent.

Viewport: todo
Visual: todo
View cube: todo

WPF¶

Note

This section is under construction. Please contribute!

The HelixToolkit.Wpf package makes it easier to work with the 3D functionality of WPF.

Getting started¶

Note

This section is under construction. Please contribute!

Adding the “HelixToolkit.Wpf” NuGet package
Adding a HelixViewport3D control
Adding content

Adding the “HelixToolkit.Wpf” NuGet package¶

You can add a NuGet package by right clicking on your project, and then selecting manage NuGet packages .... There you can search for and add HelixToolkit.Wpf.

Adding the toolkit to your xaml¶

in the Window node of your xaml you have to add a new key to reference the toolkit. It should look like xmlns:HelixToolkit=”clr-namespace:HelixToolkit.Wpf;assembly=HelixToolkit.Wpf”. This makes your window look something like:

<Window x:Class="YourNamespace.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:HelixToolkit="clr-namespace:HelixToolkit.Wpf;assembly=HelixToolkit.Wpf"
        xmlns:local="clr-namespace:YourNamespace"
        mc:Ignorable="d"
        Title="MainWindow" Height="350" Width="525">

Adding a viewport control¶

Now you can add the helix viewport control like you would add a regular 3D control. Your Grid should now contain:

<HelixToolkit:HelixViewport3D ZoomExtentsWhenLoaded="True">
    <!-- Remember to add light to the scene -->
    <HelixToolkit:SunLight/>
    <ModelVisual3D>
        <ModelVisual3D.Content>
            <GeometryModel3D>
                <GeometryModel3D.Geometry>
                    <MeshGeometry3D x:Name="meshMain"
                        Positions="0 0 0  1 0 0  0 1 0  1 1 0  0 0 1  1 0 1  0 1 1  1 1 1"
                        TriangleIndices="2 3 1  2 1 0  7 1 3  7 5 1  6 5 7  6 4 5  6 2 0  2 0 4  2 7 3  2 6 7  0 1 5  0 5 4">
                    </MeshGeometry3D>
                </GeometryModel3D.Geometry>
                <GeometryModel3D.Material>
                    <DiffuseMaterial x:Name="matDiffuseMain">
                        <DiffuseMaterial.Brush>
                            <SolidColorBrush Color="Gray"/>
                        </DiffuseMaterial.Brush>
                    </DiffuseMaterial>
                </GeometryModel3D.Material>
            </GeometryModel3D>
        </ModelVisual3D.Content>
    </ModelVisual3D>
    <HelixToolkit:GridLinesVisual3D Width="8" Length="8" MinorDistance="1" MajorDistance="1" Thickness="0.01"/>
</HelixToolkit:HelixViewport3D>

You can also see simple examples on the repository of helix-toolkit.

WPF + SharpDX¶

Note

This section is under construction. Please contribute!

The HelixToolkit.Wpf.SharpDX package makes it easier to work with SharpDX in WPF.

Getting started¶

Note

This section is under construction. Please contribute!

Adding the “HelixToolkit.Wpf.SharpDX” NuGet package
Adding a viewport control
Adding content

Contribute¶

How to contribute¶

Note

This section is under construction. Please contribute!

Introduction¶

Contributions to this project, whether new features or bug fixes, are deeply appreciated and benefit the whole user community.

The following guidelines help ensure the smooth running of the project, and keep a consistent standard across the codebase. They are guidelines only - should you feel a need to deviate from them it is probably for a good reason - but please adhere to them as closely as possible.

Making contributions¶

If you would like to contribute code or documentation to the project, we welcome pull requests.

New features and bugs should always be added in the issue tracker. It might be a good idea to discuss in the forum first if you are not sure if it is a bug or a feature we want to include in the library.

License¶

See the License page. Your contributions must be your own work and licensed under the same terms as Helix Toolkit.

Branches¶

The repository contains two branches:

master - the release branch (stable channel)
develop - the main branch with the latest development changes (pre-release channel)

See A successful git branching model for more information about the branching model in use.

Process¶

Search the issue tracker to see if the bug or new feature is already there.
If not, create a new issue
Wait for the issue to be tagged
Create a fork, branch, do the changes, commit, rebase, push
Create a pull request

The changes will be reviewed and merged into the origin if everything is OK.

Working with Git¶

Log in to GitHub and open the origin repository. Click the “Fork” button to create your own fork of the repository.
Create a clone on your local system: git clone https://github.com/yourusername/helix-toolkit.git
Create a branch for the bugfix/feature you want to work on: git branch bugfix-some-error
Checkout the branch: git checkout bugfix-some-error
Commit your changes: git commit -m <msg>
Rebase interactively (“squash”) to the latest commit of the origin
Push: git push
Open the GitHub page for your fork and create a “Pull Request”
Include the issue number in the pull request comment (not in the title where it will not be linked!)

Commit messages¶

Please follow the style of the other messages in the commit history. Explain the intentions for the change and include the issue number.

Requirements for pull requests¶

The pull request should be based on the latest commit on the develop branch of the origin repository
Include examples or unit tests for the change / new feature
Update the CHANGELOG.md file
Make sure the code builds
Make sure all unit tests are passing
Follow the Coding style, make sure there are no StyleCop issues
squash each logical change to a single commit

And please:

create a branch/pull request for each issue, do not combine multiple issues
define full name and e-mail address in the change list user information
update the AUTHORS and CONTRIBUTORS files if you are not already listed there
include the issue number in the commit message, e.g. “#9945”
follow the style of the existing commit messages

Issues¶

Note

This section is under construction. Please contribute!

Please use the discussion forum if you are unsure whether it is a bug in the library or a problem in your code.
When you are sure, please add defects directly in the issue tracker.
It is very helpful to get the generated code (use CTRL+ALT+C in the plot control) and report (CTRL+ALT+R) of the bug plot
You could use services like http://snipt.org or https://gist.github.com to share code snippets.
Images can easily be included both in the forum and the issue tracker

Build¶

Note

This section is under construction. Please contribute!

Requirements¶

.NET 3.5 or later
Build tool with support for Portable Class Libraries (Visual Studio 201x, MsBuild)
StyleCop

The solutions can be opened in

VS 2010 (with the Portable Library Tools extension)
VS 2012 (with the latest update)
VS 2013
VS 2013 CE
VS 2015

VS Express does not support Portable Class Libraries, and cannot be used to build this project.

Depending on what platform you want to build, you may need to install extra SDKs or target framework profiles

Obtain the source code¶

This project is using Git distributed version control system (DVCS). To obtain the code, it is recommended to install one of the following Git clients

GitHub for Windows
SourceTree (for Windows and Mac)
TortoiseGit (Windows shell extension)
Git (command line)

Clone the repository from https://github.com/helix-toolkit/helix-toolkit.git. This can be done by the following command line:

git clone https://github.com/helix-toolkit/helix-toolkit.git

If you don’t want to use Git, you can also obtain the complete source code as a .zip archive from the repository page. Click the “Download Zip” button.

Build¶

It should be possible to open the solution and build with Visual Studio or msbuild without any additional steps.

Build output¶

The build output of the Release configurations are placed in the Output/ folder. The output of the Debug configurations are placed under the Source/*/bin/Debug folders.

Coding style¶

write StyleCop compliant code
include XML comments for all methods, properties and fields
do not use #regions
use linq method syntax (not query syntax)
keep it simple

Architecture¶

Note

This section is under construction. Please contribute!

show some diagrams?
something about the components and dependencies?
architecture issues?

Documentation¶

Note

This section is under construction. Please contribute!

API documentation¶

The API documentation is generated from the XML comments included in the source code. All methods and properties should be documented in compliance with the StyleCop rules.

User’s guide¶

The user’s guide contains “hand-written” information about the library. The user’s guide is provided online (html) and as a printable file (pdf).

Contributions¶

Contributions to the documentation should be done the same way as for code. Clone the repository, create a branch and submit a pull request when the changes are ready.

Web site¶

The source of the helix-toolkit.org web site can be found in the helix-toolkit.github.io repository.

The web-site is built by GitHub with Jekyll.

Please contribute by creating pull requests in the helix-toolkit.github.io repository.

Welcome to Helix Toolkit’s documentation!¶

Content¶

Introduction¶

Introduction¶

Background¶

Features¶

Portable code¶

WPF¶

WPF+SharpDX¶

License¶

Authors¶

Contributors¶

Getting Support¶

Community Support¶

Commercial Support¶

Frequently asked questions¶

Where is the source code?¶

Where can I find examples?¶

Glossary¶

WPF¶

Getting started¶

Adding the “HelixToolkit.Wpf” NuGet package¶

Adding the toolkit to your xaml¶

Adding a viewport control¶

WPF + SharpDX¶

Getting started¶

Contribute¶

How to contribute¶

Introduction¶

Making contributions¶

License¶

Branches¶

Process¶

Working with Git¶

Commit messages¶

Requirements for pull requests¶

Issues¶

Build¶

Requirements¶

Obtain the source code¶

Build¶

Build output¶

Coding style¶

Architecture¶

Documentation¶

API documentation¶

User’s guide¶

Contributions¶

Web site¶

Indices and tables¶