This software was created to help with the development of 3D models of planets, moons and so on, used in the non-profit project A Touch of The Universe on educational astronomy.
There are several programs related to images of maps and 3D files:
mapelia- convert maps into 3D figures with reliefsguapelia- optional GUI to use mapeliapintelia- convert maps into colored 3D figurespoligoniza- form faces (polygons) from 3D pointsstl-split- split a 3D globe into the north and south hemispheressmooth- create a smoothed version of an image
The images are jpg or png files that contain maps (that is,
gridded datasets where the value of each pixel is the elevation) in
any of the following projections:
equirectangular,
Mercator,
central
cylindrical,
Mollweide or
sinusoidal.
The output of the programs are 3D files (of polygons like ply or stl, or points in space like asc), that can be visualized and manipulated with programs like MeshLab or Blender.
In the project A Touch of The Universe, the generated stl files
are printed with a 3D printer, to create a physical representation of
diverse planets and moons. Those printed models are then used to do
outreach in astronomy at the Aula del Cel (The Sky
Classroom) in the
Astronomical Observatory of the University of Valencia among other
places.
Just download this repository, go to its folder and run:
$ pip install -e .Or, if you already have installed the prerequisites (mainly numpy
and pillow, see below), then you can directly run the programs.
The main computation is done with projections.py, but we can create
a faster compiled module. To do it, you can add the optional cython
dependency:
$ pip install -e '.[cython]'Then, you can run:
$ python setup.py developIf you don't do it, mapelia will still work, but just using the
slower version.
All the programs need Python 3 to run. In addition, most need the following packages: Pillow and NumPy.
On a recent Debian system, you can install them with:
$ sudo apt install python3 python3-pil python3-numpyThis will allow you to run mapelia, pintelia, poligoniza,
stl-split and smooth.
If you haven't installed them with pip install -e . you can still
run them like ./mapelia/mapelia.py and so on.
In case you want to use the optional Graphical User Interface
guapelia you will also need GTK+
3.
$ sudo apt install python3-gi libgtk-3-0You can run some tests that use maps from the examples directory
with:
$ ./tests.py- ply - "polygons" in 3D, also admits colors
- stl -
"stereolitography", triangles in 3D, not as nice as
plybut much used for 3D printing - asc - only 3D points
- Pillow - Python Imaging Library
- NumPy - library with support for multi-dimensional arrays
- MeshLab - program to view and edit 3D meshes
- Blender - 3D computer graphics toolset
This program is licensed under the GPL v3. See the project license for further details.
mapelia is a program to manipulate files with map images and
transform them into 3D figures with their heights extracted from the
map.
Starting with the following image:
we run:
$ mapelia examples/venus.png
Processing file examples/venus.png ...
- Extracting heights from image (channel "val")...
Adding north cap...
- Forming faces...
Adding map...
- Projecting heights on a sphere...
- Forming faces...
Stitching patches...
- Forming faces...
Adding south cap...
- Forming faces...
Stitching patches...
- Forming faces...
The output is in file examples/venus.plyand get:
usage: mapelia [-h] [--output OUTPUT] [--overwrite] [--type {ply,asc,stl}]
[--channel {r,g,b,average,hue,sat,val,color}] [--invert]
[--projection {mercator,central-cylindrical,mollweide,equirectangular,sinusoidal,half-sphere}]
[--points POINTS] [--scale SCALE] [--caps CAPS]
[--caps-height CAPS_HEIGHT] [--logo-north LOGO_NORTH]
[--logo-north-scale LOGO_NORTH_SCALE] [--logo-south LOGO_SOUTH]
[--logo-south-scale LOGO_SOUTH_SCALE]
[--meridians-pos [POSITION [POSITION ...]]]
[--meridians-widths [WIDTH [WIDTH ...]]]
[--meridians-height MERIDIANS_HEIGHT]
[--equator-width EQUATOR_WIDTH]
[--equator-height EQUATOR_HEIGHT] [--thickness THICKNESS]
[--no-ratio-check] [--no-faces] [--no-close-figure]
[--blur BLUR] [--fix-gaps] [--config CONFIG]
image
Transform images with maps into 3D files. It takes maps images in jpg, png and
so on, and writes 3D polygon files (ply and stl) or clouds of 3D points (asc)
with a sphere that contains the elevations deduced from the map at each point.
These files can be further processed with programs like MeshLab or Blender.
positional arguments:
image image file with the map
optional arguments:
-h, --help show this help message and exit
--output OUTPUT output file (if empty, it is generated from the image
file name) (default: )
--overwrite do not check if the output file already exists
(default: False)
--type ply_asc_stl type of 3D file to generate (default: ply)
--channel r_g_b_average_hue_sat_val_color
channel with the elevations information in the image
(default: val)
--invert invert heights (default: False)
--projection mercator_central-cylindrical_mollweide_equirectangular_sinusoidal_half-sphere
projection used in the map (default: mercator)
--points POINTS maximum number of points to use (or 0 to use all in
the image) (default: 0)
--scale SCALE fraction of radius between the highest and lowest
points (default: 0.02)
--caps CAPS angle (in degrees) where the caps end (or auto or
none) (default: auto)
--caps-height CAPS_HEIGHT
height of the caps (1 would be at sea-level) (default:
1.02)
--logo-north LOGO_NORTH
image file with the north logo (default: )
--logo-north-scale LOGO_NORTH_SCALE
scale factor for the north logo (can be < 0 for
engravings) (default: 1.0)
--logo-south LOGO_SOUTH
image file with the south logo (default: )
--logo-south-scale LOGO_SOUTH_SCALE
scale factor for the south logo (can be < 0 for
engravings) (default: 1.0)
--meridians-pos POSITION1_POSITION2_etc
list of longitudes (in degrees) with meridians
(default: [0])
--meridians-widths WIDTH1_WIDTH2_etc
list of widths (in degrees) of the meridians (default:
[2])
--meridians-height MERIDIANS_HEIGHT
elevation of the meridians (at the equator) (default:
1.02)
--equator-width EQUATOR_WIDTH
width (in degrees) of the equator (0 for no equator)
(default: 0)
--equator-height EQUATOR_HEIGHT
elevation of the equator (default: 1.02)
--thickness THICKNESS
thickness of the generated object (< 1 for partially
hollow)) (default: 1)
--no-ratio-check do not fix the height/width ratio for certain
projections (default: False)
--no-faces add no faces, only points (default: False)
--no-close-figure do not stitch borders (default: False)
--blur BLUR amount of pixels used to smooth the image (default: 0)
--fix-gaps try to fill the gaps in the map (default: False)
--config CONFIG file with default parameters (default: )
pintelia is a program to project maps into 3D spheres with the
original colors of the map.
By running:
$ pintelia examples/earth_equirectangular.jpg --proj equirectangular
Processing file examples/earth_equirectangular.jpg ...
- Forming faces...
The output is in file examples/earth_equirectangular.plywe get:
usage: pintelia [-h] [-o OUTPUT] [--overwrite]
[--projection {mercator,cylindrical,mollweide,equirectangular,sinusoidal}]
[--points POINTS] [--no-ratio-check] [--fix-gaps]
image
Paint with colors over the surface of a sphere an image with a map. It takes
maps from jpg files, png, and so on, and writes ply (polygon) files.
positional arguments:
image image file with the map
optional arguments:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
output file (if empty, it is generated from the image
file name) (default: )
--overwrite do not check if the output file already exists
(default: False)
--projection mercator_central-cylindrical_mollweide_equirectangular_sinusoidal
projection used in the map (default: mercator)
--points POINTS maximum number of points to use (or 0 to use all in
the image) (default: 0)
--no-ratio-check do not fix the height/width ratio for certain
projections (default: False)
--fix-gaps try to fill the gaps in the map (default: False)
poligoniza takes files of 3D points (.asc) and tries to join them
forming the faces of a solid.
The points in the original file must be in a certain order so that the
faces are correctly formed. For example, the order in which mapelia
generates the points (when it does not project logos too).
$ poligoniza venus.asc --type stl --invert
Processing file venus.asc ...
- Forming faces...
The output is in file venus.stlusage: poligoniza [-h] [-o OUTPUT] [--overwrite] [--type {ply,stl}] [--ascii]
[--invert] [--row-length ROW_LENGTH]
file
Create a file of polygons (.ply or .stl) from one with only the 3D points
(.asc). The original asc file must have the points in the order that
corresponds to the sections of a quasi-spherical object.
positional arguments:
file asc file with the points coordinates
optional arguments:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
output file (if empty, it is generated from the image
file name) (default: )
--overwrite do not check if the output file already exists
(default: False)
--type ply_stl type of 3D file to generate (default: ply)
--ascii write the resulting ply file in ascii (default: False)
--invert invert the orientations of the faces (default: False)
--row-length ROW_LENGTH
maximum number of points to use (or 0 to autodetect)
Split an stl into its north and south hemispheres. Optionally, split it into two files with all the points before and after a given one.
$ stl-split mars.stl
Processing file mars.stl ...
Writing file mars_N.stl ...
Writing file mars_S.stl ...usage: stl-split [-h] [-n NAME] [--zcut ZCUT] [--discard-border]
[--number NUMBER] [--overwrite] [--ignore-check]
file
Split an stl file. The idea is to help post-processing stl files made with
mapelia, so they can be printed more easily. It does not modify the original
file, but creates two new files that end with "_N.stl" and "_S.stl" (or
"_head.stl" and "_tail.stl" if using the option --number).
positional arguments:
file stl file
optional arguments:
-h, --help show this help message and exit
-n NAME, --name NAME output file (if empty, it is generated from the image
file name) (default: )
--zcut ZCUT z value of the cutting xy-plane (or auto) (default: 0)
--discard-border put triangles not cleanly cut in a "_discarded.stl"
file (default: False)
--number NUMBER split by leaving a given number of triangles in the
first file (default: 0)
--overwrite do not check if the output files already exist
(default: False)
--ignore-check go ahead even if the input file does not look like an
stl (default: False)
Create a smoothed version of an image.
$ smooth starmap.jpg
Writing file starmap_smoothed.jpg ...usage: smooth [-h] [--output OUTPUT] [--overwrite] [--invert]
[--intensity INTENSITY]
image
Create a smoothed version of an image.
positional arguments:
image image file with the map
optional arguments:
-h, --help show this help message and exit
--output OUTPUT output file (if empty, it is generated from the image
file name) (default: )
--overwrite do not check if the output file already exists
(default: False)
--invert invert the colors of the image (default: False)
--intensity INTENSITY
intensity of the smoothing (default: 10)