Skip to content
Scripts to create vector fields and flow maps that can be used in Unreal Engine 4 or Unity 3D for particle VFX.
Branch: master
Clone or download
Latest commit 7ea6f02 Feb 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs/img Belt2D as UE4 example Feb 13, 2019
src/vectorfields allow upper case extensions Feb 13, 2019
.gitignore update gitignore Jan 23, 2019
LICENSE Initial commit Jan 23, 2019
MANIFEST.in preparing setup Jan 23, 2019
README.md Anaconda numpy warning Feb 13, 2019
setup.cfg preparing setup Jan 23, 2019
setup.py flowmaps Feb 2, 2019

README.md

VectorFields

Scripts to create vector fields and flowmaps that can be used in game engines like Unreal Engine 4 and Unity 3D.
Have a look at UE4's documentation.

Installation

via Python Package Index

pip install vectorfields

Bleeding Edge

  • To install using development mode:
    pip install -e git+https://github.com/OlafHaag/vectorfields.git@master#egg=vectorfields
  • To install using regular mode (building the package):
    pip install https://github.com/OlafHaag/vectorfields/archive/master.zip

Anaconda Warning

To cite Ralf Gommers:

please never install numpy with pip into a conda/anaconda install! This will result in all sorts of pain down the line.

So if you use the Anaconda distribution and you run into the issue Importing the multiarray numpy extension module failed.: Use conda to install numpy beforehand or pip uninstall numpy and reinstall numpy with conda install numpy into your environment.

Usage

You have to know a bit of python and math.

The abstract base classes VectorField and VectorField2D can't be instantiated.

Instantiate a specific vector field, like ElectricDipole2D.
You can use the save method to write the vector field to disk in FGA or VF format. To be able to save in vf format, you have to turn instances of VectorField2D subclasses into 3D vector fields with the to_3d method. If I'm not mistaken Unity expects cubic vector fields with resolution x=y=z. You can also save instances of Vectorfield2D's sub classes to flow maps (e.g. png).

It's best to preview your vector field directly in engine. Saving to disk usually reloads the file in Unity.
For other purposes you can use the plot-method of the Vectorfield2D class to get a preview.

Special classes

Vortex2D

Has parameters radius and pull.
Vortex2D Example Animation

TwirlFlow2D

TwirlFlow2D Example Animation

ElectricDipole2D

ElectricDipole2D has 2 special methods to either normalize the vectors and lose all information on field strength or to clamp the field strength to a maximum value. This was necessary, because the physical properties of this field aren't visually pleasing.
ElectricDipole Example Animation

Belt2D

With this you can place rotating areas in the field that more or less merge together, hence creating the impression of a belt running over pulleys.
Besides their x and y coordinates each pulley has a radius, thickness and speed (negative speed to change direction). Belt2D Example Animation
As a flowmap:
Belt2D Example Flowmap

CustomUVW

This is a class for quick prototyping and generation of vector fields.

You provide custom functions to the constructor for creating the U, V and W vector components.
These functions must take 3 parameters that will be substituted for the class' data members grid_x, grid_y, grid_z.
The return value must be an array of the same shape as grid_x, grid_y or grid_z respectively.

CustomUV2D

This is a class for quick prototyping and generation of 2D vectorfields.

You provide custom functions to the constructor for creating the U and V vector components.
These functions must take 2 parameters that will be substituted for the class' data members grid_x and grid_y. The return value must be an array of the same shape as grid_x or grid_y respectively.

2D Examples:

non-square sine vector field

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.ones(x.shape)  # Flow in one direction.
vfunc = lambda x,y: np.sin(x)
vf = CustomUV2D(ufunc, vfunc, size=[8,2], resolution=[32,8])

square example: Sine Wave Example Animation

regular cosine whirls

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.cos(y)
vfunc = lambda x,y: np.cos(x)
vf = CustomUV2D(ufunc, vfunc, size=16)

Diamonds Example Animation

"flowers"

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.sin(y + x)
vfunc = lambda x,y: np.cos(x - y)
vf = CustomUV2D(ufunc, vfunc, size=12, resolution=48)

Belt2D Example Animation

some diagonal flow thingy

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.cos(np.sqrt(np.abs(x)))  
vfunc = lambda x,y: np.cos(np.sqrt(np.abs(y)))  
vf = CustomUV2D(ufunc, vfunc)

anvaka's square flow tiles (seriously, it's hard to find names for this stuff)

import numpy as np
from vectorfields import CustomUV2D  
ufunc = lambda x,y: 2.0 * np.mod(np.floor(-y), 2.0) - 1.0
vfunc = lambda x,y: 2.0 * np.mod(np.floor(-x), -2.0) + 1.0
vf = CustomUV2D(ufunc, vfunc, size=5.9, resolution=24)

beautiful twirls

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.cos(np.linalg.norm(np.dstack((x, y)), axis=2))[:,:,np.newaxis]
vfunc = lambda x,y: np.cos(x-y)
vf = CustomUV2D(ufunc, vfunc, size=16)

Twirls Example Animation

twirl column

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.sin(y)
vfunc = lambda x,y: x
vf = CustomUV2D(ufunc, vfunc, size=[12, 16], resolution=[24, 32])

One last thingy...

import numpy as np
from vectorfields import CustomUV2D
ufunc = lambda x,y: np.cos(y**2)
vfunc = lambda x,y: np.cos(y*x)
vf = CustomUV2D(ufunc, vfunc, size=[24, 16], resolution=[48,32])

Thingy Example Animation

History

This little project started at a little game jam with the topic "electricity". I wanted to do something with particles and controlling their flow with formulas, but the available methods for creating vector fields at the time where either too complicated for this small task, or too time consuming or bound to purchasing a software license. Of course, this cannot compete with GUI software like VectorayGen, but it's free and open source.

Development

Since it did what I needed it got stuck in early development stage. For example, there's a lack of three-dimensional vector field examples and there are no unit-tests.

I'd like to see people creating other vector fields with this and improve and advance the code.

You can’t perform that action at this time.