Roller: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(→‎Roller: Updated for issues #30, #34, 37)
(Deleted most of the information since it is out of date. Info moved to our wiki.)
Line 5: Line 5:
Roller is a community made software developed by Spooner to convert and process OFP and ArmA island files.
Roller is a community made software developed by Spooner to convert and process OFP and ArmA island files.


It can read:
Its primary purpose is to convert OFP islands to ArmA for the ACE Island Pack, but it can also do some processing that could be useful to people making new ArmA islands.
 
* 4WVR WRP (OFP unbinarized)
* 8WVR WRP (ArmA unbinarized)
 
It can write:
 
* 8WVR WRP (ArmA unbinarized)
* XYZ height data (text file)
* Object data list (text file)
* Mask texture (PNG)
 
Additional features
 
* Generate Mask texture (customizable coloring based on terrain point height, definition of forest and urban areas, customizable texture size)
* Replace forest block with customizable single objects (type, density, relative frequency)
* Replace single objects with optional offset (1:n and n:1)
* Reduce cell size for more height data points (smooth terrain shape)
* Make terrain bumpy
* Rise/lower sea level
* Generate list of unique objects present in source file
* Replace textures (1:n and n:1)
* Set terrain point height at the edges (to avoid endless repeated terrain)
* Processing summary


==Project links==
==Project links==
Line 43: Line 20:
* [http://rm.6thsense.eu/projects/list_files/roller Roller download area]
* [http://rm.6thsense.eu/projects/list_files/roller Roller download area]


==Preface==
==Roller Dev Team==
 
You need be able to use the command line or at least able to edit a batch file to tell the app what to do. There is no GUI available to access the app. The app can be called sequentially to perform a batch operation to process multiple files easily.
 
==Installation==
 
===Requirements===
 
* Download and install [[Visitor_3|Visitor 3]] as well as buldozer.
* This means to have a P:\ partition with all ArmA source files available.
** Install [[BI_Tools|BI Tools]] first.
** Use [http://www.armaholic.com/page.php?id=3320 unBuildArmA] by MadDogX to mass unpack all ArmA pbos to P:\ or use [http://www.armaholic.com/page.php?id=411 cpbo] by Kegetys to do it one by one yourself.
** Download and unpack the [http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi?act=ST;f=61;t=67070 BI Sample Models] to P:\. Overwrite existing files.
* No requirements for Roller. Its a self-contained application.
 
===Download===
 
* [http://rm.6thsense.eu/projects/list_files/roller End user version]
* [http://rm.6thsense.eu/projects/list_files/roller Open source version]
 
For the source you need at least [http://www.ruby-lang.org/en/downloads/ Ruby 1.8.6] installed, along with FXRuby (this is included in the Ruby installer for Windows, but is easily available as a gem if it is not included in your distribution).
Recommended development IDE is [http://www.netbeans.org/downloads/index.html NetBeans IDE] 'Ruby' version.
 
====Additional helpers====
 
* Object definition templates (ODT). To be able to import the given objects in v3 they must be defined first. These PEW files contain different sets of object definitions:<br><br>
** [http://rm.6thsense.eu/projects/list_files/roller A1 objects] (v3_object_definition_template_A1_objects.pew)
** [http://rm.6thsense.eu/projects/list_files/roller ACEIP_objects] (v3_object_definition_template_ACEIP_objects.pew)
** [http://rm.6thsense.eu/projects/list_files/roller OFP 3rdParty objects] (v3_object_definition_template_OFP_3rdParty_objects.pew)
** [http://rm.6thsense.eu/projects/list_files/roller OFP_objects] (v3_object_definition_template_OFP_objects.pew)
 
* Sample PEW files for OFP standard island files. They already contain all the ODT. The texture is set to the ACEIP Everon by default. Yet it can be easily changed via v3. Terrain cell size is set to 50 meters. Terrain grid size:<br><br>
** [http://rm.6thsense.eu/projects/list_files/roller 128]
** [http://rm.6thsense.eu/projects/list_files/roller 256]
** [http://rm.6thsense.eu/projects/list_files/roller 512]
** [http://rm.6thsense.eu/projects/list_files/roller 1024]
 
==Instructions==
 
===Roller===
 
{| class="wikitable"
|-
! short param
! width="180"|paramater
! width="120"|type
! description
|-
| -F
| --replace-forests A,B,C
| Comma-separated list of filenames
| Replace OFP forest block objects with individual trees and bushes, according to comma-separated list of YAML files (occurs after object replacement)
|-
| -o
| --replace-objects A,B,C
| Comma-separated list of filenames
| Replace objects according to comma-separated list of YAML files (occurs before forest replacement)
|-
| -t
| --replace-textures A,B,C
| Comma-separated list of filenames
| Replace textures according to comma-separated list of YAML files
|-
| -c
| --terrain-cell-size N
| Float
| Set new size of terrain cells (metres). This must give a legal grid size of 16x16 to 4096x4096 cells (e.g. for an island imported from OFP, which has 50m cells, you could resize to 800, 400, 200, 100, 25, 12.5, 6.25 or 3.125).
|-
| -b
| --terrain-bumpiness N
| Float
| Maximum amount of vertical distortion of new grid points added by terrain-cell-size (metres). Applied after terrain cell resizing, but before other changes.
|-
| -r
| --raise-sea-level N
| Float
| Move sea level up by this distance (move sea level down if negative). Done before edge-height is set
|-
| -e
| --edge-height N
| Float
| Sets the height of all terrain points around the edge to a specific value. This is applied after cell, bumpiness and sea-level changes.
|-
| -m
| --satellite-mask [FILE]
| String (optional)
| Export a satellite mask PNG image (FILE defaults to 'WRPFILE_mask.png')
|-
| -C
| --satellite-cell-size N
| Float
| Size of satellite cells, i.e. pixels, in metres (defaults to 2 metres if this option is omitted)
|-
| -O
| --objects [FILE]
| String (optional)
| Export BIS objects file (FILE defaults to 'WRPFILE_objects.txt')
|-
| -u
| --unique-objects [FILE]
| String (optional)
| Export a list of objects used in the WRP (FILE defaults to 'WRPFILE_unique_objects.txt')
|-
| -w
| --wrp [FILE]
| String (optional)
| Export WRP file in 8WVR format, regardless of which format it was imported as (FILE defaults to 'WRPFILE_export.wrp')
|-
| -x
| --xyz [FILE]
| String (optional)
| Export XYZ file (FILE defaults to 'WRPFILE.xyz')
|-
| -p
| --show-progress
|
| Show the graphical progress bar (which will slow down all import, export and processing slightly).
|-
| -f
| --force-overwrite
|
| Forces overwriting of existing output files (defaults to requesting user confirmation of overwrites)
|-
|}
 
===Visitor 3===
 
The conversion process is very simple and only takes a few minutes. The goal is to have as much as possible automated, so that only these tasks remain:
 
'''1)''' Read the 4WVR/8WVR WRP with Roller and set the correct params for Roller. Normally you at least need :
 
-x -O -u
 
'''2)''' Get the ''XYZ file'' (elevation data). Get the ''objects file'' (all objects of the map). X, Y, Z position and orientation are exported for each object. Unfortunately v3 cannot import object scale. Also the object orientation is 2d only (N/E/S/W. No 3rd dimension: pitch).
 
This fact does not really hurt though. Both are normally only applied on vegetation and you can easily recreate a similar look via v3 random object scale and pitch functions.
 
'''3)''' Create a new project in v3 with the right dimensions and cell size (OFP default 50 meters). For more details or information about SAT settings consult the [[Visitor_3_Manual|Visitor 3 Manual]].
 
<br clear="all" />
[[Image:V3_Project_Parameters.jpg|thumb|250 px|Project parameters in Visitor 3|left]]
<br clear="all" />
 
'''4)''' Import the XYZ file to get the actual terrain.
 
<br clear="all" />
[[Image:V3_Import_XYZ.jpg|thumb|250 px|Import XYZ in Visitor 3|left]]
<br clear="all" />
 
'''5)''' Import one ore more ''object definition template PEWs (ODT)''. To be able to import objects from object definition template files v3 needs to know the model and its path. Fortunately the information about models is saved in a PEW and you can import that definition in your PEW from another PEW.
 
You can download ''object definition template PEWs'' that includes all OFP, ArmA objects, as well as some ACE island pack objects. More details on object definition templates in general and the ACEIP objects below.
 
'''6)''' Import the object definition template(s).
 
<br clear="all" />
[[Image:V3_Import_Object_Templates.jpg|thumb|250 px|Import object definition template PEWs in Visitor 3|left]]
<br clear="all" />
 
'''7)''' Import the island objects from the objects file generate by Roller. If not done already, you need to add the ''ImportObjects.vis'' script to visitor 3 first. You will find the file in the ''.\visitor 3\scripts'' folder.
 
<br clear="all" />
[[Image:V3_Import_Objects_Scripts.jpg|thumb|250 px|Import objects in Visitor 3|left]]
<br clear="all" />
 
'''8)''' Load the terrain with buldozer and export the island to 8WVR WRP. You need to have buldozer loaded, switch back to v3 and select export world.
 
<br clear="all" />
[[Image:V3_Export_World.jpg|thumb|250 px|Start buldozer and export world to a WRP file in Visitor 3|left]]
<br clear="all" />
 
Done. This course of action takes only a couple of minutes.
 
===Details===
 
====Objects====
 
The island most likely has OFP object addons. These do not exist in ArmA. We have to differentiate between ''OFP and Resistance objects'', that came with the game, and ''community made objects''. There are a few different options how to the handle the objects.
 
=====Object replacement=====
 
Roller has the option to replace objects with the param '''--replace-objects'''. The mapping is defined in a so called YAML file. It is a standard text file.
 
--replace-objects ofp_objects_to_aceip_objects.yaml,ofp_objects_to_arma_objects.yaml
 
You need to supply the param with at least one YAML file. If you attach multiple YAML files, they will be processed sequentially one after another.
 
An object replacement YAML mapping file looks like this:
 
data3d\afbarabizna.p3d:
  -
    :name: ca\buildings\afbarabizna.p3d
    :offset: [0, 0, 0]
data3d\afdum_mesto2.p3d:
  -
    :name: ca\buildings\afdum_mesto2.p3d
    :offset: [0, 0, 0]
 
# pathToFile\nameOfFile.p3d:
#  -
#    :name: pathToReplacementFile\subfolder\nameOfReplacementFile.p3d
#    :offset: [X, Y, Z]
 
Via the offset you can move the object in meters in any direction you want to.
 
The YAML file needs to be located in the same location as TODO.
 
For an 1:n replacement define the object mapping in the YAML like this:
 
data3d\oliva.p3d:
  -
    :name: ace_vegetation_obj\m\tree\ace_akat02.p3d
    :offset: [0, 0, 0]
  -
    :name: ace_vegetation_obj\m\tree\ace_javor01.p3d
    :offset: [0, 0, 0]
 
An n:1 mapping is replacing any object with one and the same of course.
 
n:1 means ''make object X, Y and Z to object A''.
1:n means ''make object X to either object A or B''.
 
=====Object mapping - OFP to ArmA YAML file=====
 
Roller already has a mapping for OFP and Resistance (NOT community addons, only for core game files) integrated. The name is ''ofp_objects_to_arma_objects.yaml''. Roller will find the file automatically, if you there is no YAML file called the same way in the TODO location.
 
You can download the ''ofp_objects_to_arma_objects.yaml'' file [http://www.ofpec.com/ here].
 
Unfortunately there is no (working replacement) for each OFP/Resistance objects. You can either define your own mapping or use the OFP to ACE mapping.
More details in the next paragraph.
 
=====Object mapping - OFP to ACE YAML file=====
 
This is again a mapping integrated into Roller. Same details apply for it how to run it as for the ''ofp_objects_to_arma_objects.yaml'' file.
 
You can download the ''ofp_objects_to_aceip_objects.yaml'' file [http://www.ofpec.com/ here].
 
The-f made a mapping from OFP to ArmA objects for the objects where a suitable replacement was available. The remaining objects, that have no (working) replacement in ArmA, have been converted to ArmA and are part of the [[ACE:IslandPack|ACEIP]].
 
You can either define your own mapping or use the objects from the ACEIP. Beware that this makes your islands dependent on the addons part of the ACEIP.
 
=====Community made OFP objects=====
 
For custom community made OFP objects you need to define your own replacement. You can either get the permission for the object(s), convert them to ArmA format or replace them with any (suitable) object available in ArmA.
 
If you do not define a mapping, v3 will simply not be able to import the object. So you can just drop objects that way.
 
Note that it is recommended to replace the object with dummy object instead to preserve the object ID numbering of the source WRP.
 
Another option is to replace them with the a very tiny object from ArmA like a flower (TODO: add pathToFile). Note that you will loose the information about the source type of the given object this way.
 
It is better to create a new addon with dummy models in there. Each file has the same path and file naming as the missing object. Instead of the original model you put ''flower.p3d'' in there and rename it to the needed p3d name.
 
This way you keep the information about the correct object type. Once the object will be available in ArmA, you can replace your dummy addon / model with the correct file.
 
It is recommended to name the PBO in a proper way (your own tag and descriptive name) and use the PBOPREFIX to define the original path needed.
 
ACEIP_P_CWC
TAG TYPE p3d NAME
$PBOPREFIX$ data3d
 
Types:
f function
m mission
p p3d
s sound
t texture
w world
 
Finally the ACEIP already contains a good number of converted OFP community object addons.
 
If you make your islands based on the ACEIP, you may not have to do anything at all but to load the ''[[Tools:Roller#Additional_helpers|OFP 3rdParty objects ODT (object definition template)]]'' in v3 before you import the objects.
 
OFP community addons converted by the ACEIP:
* TODO add addon names
 
OFP community addons replaced by a dummy addon by the ACEIP:
* TODO add addon names
 
====Vegetation====
 
====Forest block objects====
 
OFP used so called forest block objects for forests. It was one model that consisted of several trees and bushes.
 
It is recommended to replace these for an ArmA WRP for performance reasons and forest blocks with partially fly at slopes as ''fit to ground'' cannot be applied in ArmA to the forest block object.
 
Roller offers a great feature to replace the forest block objects with single vegetation objects with the param ''--replace-blocks''. The mapping is defined in a so called YAML file. It is a standard text file.
 
--replace-forests ofp_forest_blocks_to_aceip_single_object_forest.yaml,ofp_forest_blocks_to_arma_single_object_forest.yaml
 
You need to supply the param with at least one YAML file. If you attach multiple YAML files, they will be processed sequentially one after another.
 
A YAML mappings look like this:
 
data3d\les ctverec pruchozi_t1.p3d:
    :sectors: [:N, :E]
    :min: 15
    :max: 30
    :models:
        ca\plants\smrk_velky.p3d: 0.3
        ca\plants\les_singlestrom.p3d: 10
        ca\plants\smrk_siroky.p3d: 0.5
        ca\plants\dd_bush01.p3d: 0.8
 
# pathToFile\nameOfFile.p3d:
#  -
#    :name: pathToReplacementFile\subfolder\nameOfReplacementFile.p3d
#    :sectors: [:orientation, :orientation]
#    :min: minmumNumberOfObjects
#    :max: maximumNumberOfObjects
#    :models:
#        pathToReplacementFile\subfolder\nameOfReplacementFile.p3d: relativeDistribution
 
Sectors defines the orientation of the forest block object. Most forest block objects have a triangular shape. So the orientation defines with sectors of the quadrangle is covered by the forest block object. For a square forest block object all forest possible orientations are listed in the sectors definition.
 
Min and max define the minimum and maximum number of objects Roller should generate in the area.
 
The models section defines which objects should be placed in the area by Roller.
The integer value after each object is added up for the one replacement and is the relative distribution compared to the other objects listed in the models section.
 
The YAML file needs to be located in the same location as TODO.
 
Roller has three forest block object replacement templates integrated. Roller will find the file automatically, if you there is no YAML file called the same way in the TODO location.
 
''ofp_forest_blocks_to_arma_single_object_forest.yaml'' ([http://www.ofpec.com/ download link]) is to replace the OFP forest block objects with ArmA vegetation.
 
''ofp_forest_blocks_to_aceip_single_object_forest.yaml'' ([http://www.ofpec.com/ download link]) is to replace the OFP forest block objects with OFP Resistance vegetation converted as part of the [[ACE:IslandPack|ACEIP]].
 
''ofp_forest_blocks_to_ofp_single_object_forest.yaml'' ([http://www.ofpec.com/ download link]) is to replace the OFP forest block objects with somewhat same type of OFP CWC and Resistance vegetation converted as part of the [[ACE:IslandPack|ACEIP]].
 
====Object export====
 
Now that we have defined any possible modifications on objects we can export them to a text file to be able import them in visitor 3 again.
 
The param ''--objects'' exports all objects to a file. If you do not define the name it will default to the name ''WRPFILE_objects.txt''.
 
====Split object export file====
 
Visitor 3 can only import up to 200 to 250 thousand objects in one go. For more objects visitor will freeze.
 
Therefore Roller also contains the helper tool called '''split.exe'''. It can split the objects export file to multiple smaller ones. You can then import them one after another. By default the files will split into 100 thousand lines each. You can define the number of lines yourself as optional parameter after the specification of the file that you want to split.
 
split.exe WRPFILE_objects.txt 200000
Usage: split.exe FILE [MAX_LINES]
 
====Unique objects list====
 
It is very useful to know what kind of objects are present in a WRP. From the list you can make the replacement YAML and identify custom community made objects.
 
 
The param ''--unique-objects'' generates a list of unique objects present in the given WRP. If you do not define the name it will default to the name ''WRPFILE_unique_objects.txt''.
 
====Special objects====
 
TODO: bridges, port walls, objects positioned on top of another object.
 
==Additional information==
 
===FAQ===
 
===Good to know===
 
* By default all objects exported by Roller are flying in v3. You need to apply the v3-tools-object manager-recalculate the elevation of objects-relative displacement to 0. If you have special objects like bridges or port walls, that won't have the right position, you need to adapt their height manual in buldozer or via v3 setAbsoluteHeight script.
 
* v3 can only import at max 200 to 250 k objects at a time. That's why split.exe is added to Roller to be able to separate an objects file with more entries than this into multiple smaller files which can be imported one after another.
 
* buldozer will crash with xyz data of 500 MB or more.
 
===Related references===
 
* [[Terrain_Editing|Terrain Editing: summary page]]
* [http://www.ofpec.com/ed_depot/index.php?action=list&game=ArmA&cat=tu&type=is ArmA Island Editing Tutorials @ OFPEC]
 
==Changelog==
 
===2008-12-31===


* ToDo
* Project manager: kyu
* Ruby developer: Spooner
* Configuration: the__f
* Testing: kyu, the__f and looz
* Roller image: Pufu

Revision as of 05:01, 6 February 2009

by the Roller Dev Team

Project Summary

Roller is a community made software developed by Spooner to convert and process OFP and ArmA island files.

Its primary purpose is to convert OFP islands to ArmA for the ACE Island Pack, but it can also do some processing that could be useful to people making new ArmA islands.

Project links

Roller Dev Team

  • Project manager: kyu
  • Ruby developer: Spooner
  • Configuration: the__f
  • Testing: kyu, the__f and looz
  • Roller image: Pufu
Retrieved from "https://community.bistudio.com/wiki?title=Roller&oldid=45720"