ud-viz
v2.39.3
Published
A framework extension of itowns.
Downloads
14
Readme
UD-Viz : Urban Data Vizualisation
UD-Viz is a JavaScript library based on iTowns, using npm and published on the npm package repository, allowing to visualize, analyse and interact with urban data.
A tutorial of the game engine can be found here
Install node/npm
For the npm installation refer here
UD-Viz has been reported to work with versions:
- node version 16 (16.13.2)
- npm version: 6.X, 7.X. and 8.X
Installing the UD-Viz library per se
git clone https://github.com/VCityTeam/UD-Viz.git
cd UD-Viz
npm install
Running the examples
cd PATH_TO_UD-Viz
npm run build
cd /
git clone https://github.com/VCityTeam/UD-SimpleServer
cd UD-SimpleServer
npm install
node index.js PATH_TO_UD-Viz 8000
- UD-Viz-Template (demonstration) application,
- online demos are available here
Developers
Pre-requisite
Developing UD-Viz requires some knowledge about JS, node.js, npm and three.js.
Developers documentation
After generation, the browsable documentation is stored within this repository.
Refer to this README to re-generate it.
Coding style
The JavaScript filees coding style is defined with eslint through the .eslintrc.js configuration file.
It can be checked (e.g. prior to a commit) with the npm run eslint
command.
Notice that UD-Viz coding style uses a unix linebreak-style
(aka LF
as newline character).
Tips for Windows developers
As configured, the coding style requires a Linux style newline characters which might be overwritten in Windows environments
(both by git
and/or your editor) to become CRLF
. When such changes happen eslint will warn about "incorrect" newline characters
(which can always be fixed with npm run eslint -- --fix
but this process quickly gets painfull).
In order to avoid such difficulties, the recommended pratice
consists in
- setting git's
core.autocrlf
tofalse
(e.g. withgit config --global core.autocrlf false
) - configure your editor/IDE to use Unix-style endings
Notes for VSCode users
When using Visual Studio Code, you can install the eslint extension allows you e.g. to automatically fix the coding style e.g. when saving a file .
Prior to PR-submission 1: assert coding style and build
Before pushing (git push
) to the origin repository please make sure to run
npm run travis
(or equivalently npm eslint
and npm run build
) in order to assert that the coding style is correct (eslint
) and that bundle (production) build (webpack
) is still effective. When failing to do so the CI won't check.
Note that when commiting (git commit
) you should make sure to provide representative messages because commit messages end-up collected in the PR message and eventually release explanations.
Prior to PR-submission 2: functionnal testing
Before submitting a pull request, and because UD-Viz still misses some tests, non regession testing must be done manually. A developlper must thus at leas) check that all the demo examples (refer to their online deployment) are still effective.
Submitting a Pull Request
When creating a PR (Pull Request) make sure to provide a correct description
Sources directory layout (organizational principles)
Definitions:
- Component: everything thats is necessary to execute only one aspect of a desired functionality (see also module).
- Extension: a component depending on a web service in order to be functionnal.
- Widget (web widget): an embedded element of a host web page but which is substantially independent of the host page (having limited or no interaction with the host). All the widget created in UD-Viz are explain here.
- Template: a class build on sibling sub-directories (Game, Widgets, Views) components and proposing an application model
- View: decorated/enhanced iTowns Views
UD-Viz (repo)
├── src # All the js sources of UD-Viz JS library
| ├── Components # A set of components used by sub-directories at this level
| ├── Templates # Classes builded with other sub-directory (Game, Widgets, Views) to propose application model
| ├── Views # Classes of 3D views encapsulating the itowns view
| ├── Game # A sub-directory offering game engine functionnality (node compatible)
| |
| └── Widgets # A sub-directory gathering a set web web widgets (UI)
| ├── Widget_1
| ├── Widget_2
| ├── ...
| └── Extensions # Widgets depending on an external web service
├── ...
└── webpack.js
Notes:
- The position of a specific component in the sub-folder hierarchy reflects
how it is shared/re-used by sub-directories. For example if a given component
is only used by a single widget, then it gets defined within that widget
folder. But when another component usage is shared by two widgets then
its definition directory gets promoted at the level of the two widgets
└── src # holds all the js sources that will be build ├── Components | └── Component_1 # A component shared by the Game and Widgets sub-directories | └── *.js ... # Component definition ├── Game | └── Component_2 # A component used by the Game sub-directory | └── ... └── Widgets ├── Components | └── Component_3 # A component shared by at least two widgets | └── ... └── Widget_1 └── Component_4 # A component only used by Widget_1 (of the Widgets sub-directory) └── ...