Volume Fill Utility¶

The volume fill utility is a command line program that can read in stl files that define geometry, then compute various fluid fill operations. The program works using a voxelization and flood fill technique. This makes the program robust with any given input STL files, but also makes the resulting accuracy sensitive to the resolution used (-n argument). The program has various functions to compute volume data given a geometry. This same utility is called from the GUI when invoking the Tools->Volume Calculator function.

Compute Modes¶

The available fill compute modes are:

Volume/height search - use the --volume X argument to search for a given volume by varying the height through a bisection search algorithm
Full volume compute - use the --full argument to compute the full volume
Curve - use the --curve argument to compute the volume vs fluid height curve data

Inputs¶

All input units are assumed to be in meters. This means your stl files must be defined using meters and any other inputs such as seed point must be in meters.

The program needs a few basic inputs in order to run:

Function to run : --volume, --full, --curve
Resolution: -n - This resolution is used to create a uniform background mesh that is used for voxelization and flood fill algorithms
Seed Point: -s - The initial point which inside the geometry which is known to be wet
Files: -f - Use this multiple times to specify the STL files. Must be meter units.
Up direction: --up - Specify which way is up

Multiple STL input files can be specified by using the -f argument multiple times. For example,

fill --full -n 200 -f  large.stl -f inner.stl --seed 0,0,0 --up yp

, would compute the full volume using the two defined stl files.

Output¶

The output is printed the standard output stream. You can also specify an option to output the results to a csv file (--out-csv), or to an xml file (--out-xml)

Usage¶

Run fill --help to show the current usage information

Usage: fill [options] [input file]

Volume Fill options:
-h [ --help ]                show help message
--volume arg                 Find the fluid height that gives the input
                                                        volume (L) using a bisection search method
--full                       Only computes full volume
--curve                      Compute volume fill curve between lowest and
                                                        highest wet points
-n [ --nx ] arg              specify resolution in X direction
-s [ --seed ] arg (=center)  specify the seed point -- "center" or
                                                        "0.1,0.1,0.2"
-f [ --file ] arg            specify the input mesh STL file
--up arg (=yp)               specify the up direction, one of: xn, yn, zn,
                                                        xp, yp, zp
--out-xml arg                Specify an output file for the data in XML
                                                        format. If left empty no file is written
--out-csv arg                Specify an output file for the curve data in CSV
                                                        format. If left empty no file is written
-N [ --max-iter ] arg (=100) specify number of iterations for volume search

Scripted Example¶

The python example below uses a sphere geometry for testing. You can download the input file here: sphere.stl.

import subprocess
from xml.etree import ElementTree as ET
import os
import math

fillexe = r'C:/PATH TO MSTAR INSTALL/fill.exe'

# inputs
# this example uses a sphere geometry
radius = 1.0
fullvol = (4./3.) * math.pi * math.pow(radius, 3) * 1000.0
halfvol = fullvol * 0.5
xmlfn = 'vol.xml'
geofn = 'sphere.stl'

# run fill utility and get results
# search for a fill volume to obtain the required fill height
compl = subprocess.run([fillexe,
                                                '-f', geofn,
                                                '--volume', str(halfvol),
                                                '-n', '300',
                                                '-s', '0,0,0',
                                                '--up', 'yp',
                                                '--out-xml', xmlfn,
                                                '--max-iter', '100' ], check=True)
tree = ET.parse(xmlfn)
root = tree.getroot()
finalResult = root.find("./VolumeSearch/FinalResult")
assert finalResult is not None, "Missing final result"
resultheight = float(finalResult.get("Height"))
resultvolume = float(finalResult.get("Volume"))  * 1000.0   # convert output from m^3 to L

# print results to screen
print (F"Finished search for volume {halfvol}. \n\tFound height {resultheight} [m]\n\tFound volume {resultvolume} [L]")

Example XML output from Fill utility in volume search mode

Note the output volumes are cubic meters.

<FillOutput VolumeUnits="m^3" LengthUnits="m">
        <VolumeSearch FindVolume="2.0943951023931953">
                <Iteration Number="0" TestHeight="1.0318185284304489" ResultVolume="2.1249517037037045" ResultVolumeError="0.03055660131050919"/>
                <Iteration Number="1" TestHeight="1.0172198424731931" ResultVolume="2.0837232592592598" ResultVolumeError="-0.010671843133935432"/>
                <Iteration Number="2" TestHeight="1.0209986628627752" ResultVolume="2.1043451851851858" ResultVolumeError="0.0099500827919904999"/>
                <Iteration Number="3" TestHeight="1.0191753813774542" ResultVolume="2.0837232592592598" ResultVolumeError="-0.010671843133935432"/>
                <Iteration Number="4" TestHeight="1.0201189292337625" ResultVolume="2.1043451851851858" ResultVolumeError="0.0099500827919904999"/>
                <Iteration Number="5" TestHeight="1.0196636672314552" ResultVolume="2.0837232592592598" ResultVolumeError="-0.010671843133935432"/>
                <Iteration Number="6" TestHeight="1.0198992652396583" ResultVolume="2.0837232592592598" ResultVolumeError="-0.010671843133935432"/>
                <FinalResult Height="1.0198992652396583" Volume="2.0837232592592598" VolumeError="-0.010671843133935432"/>
        </VolumeSearch>
</FillOutput>