From 3b355ea4045f82029bae96a8ef827729f200fa14 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Fri, 20 Dec 2024 14:36:20 +0100 Subject: [PATCH 1/2] manual: conversion of all HTML manual pages to markdown Test submission of conversion of all HTML manual pages to markdown using the `pandoc` based converter script (see #4620). For figure code conversion issues, see #4864 --- db/databaseintro.md | 107 ++ db/db.columns/db.columns.md | 52 + db/db.connect/db.connect.md | 136 ++ db/db.copy/db.copy.md | 72 + db/db.createdb/db.createdb.md | 56 + db/db.databases/db.databases.md | 46 + db/db.describe/db.describe.md | 300 ++++ db/db.drivers/db.drivers.md | 26 + db/db.dropdb/db.dropdb.md | 41 + db/db.execute/db.execute.md | 116 ++ db/db.login/db.login.md | 55 + db/db.select/db.select.md | 101 ++ db/db.tables/db.tables.md | 39 + db/drivers/dbf/grass-dbf.md | 116 ++ db/drivers/mysql/grass-mesql.md | 59 + db/drivers/mysql/grass-mysql.md | 106 ++ db/drivers/odbc/grass-odbc.md | 140 ++ db/drivers/ogr/grass-ogr.md | 7 + db/drivers/postgres/grass-pg.md | 134 ++ db/drivers/sqlite/grass-sqlite.md | 54 + display/d.barscale/d.barscale.md | 24 + display/d.colorlist/d.colorlist.md | 13 + display/d.colortable/d.colortable.md | 58 + display/d.erase/d.erase.md | 14 + display/d.extract/d.extract.md | 23 + display/d.font/d.font.md | 55 + display/d.fontlist/d.fontlist.md | 12 + display/d.geodesic/d.geodesic.md | 50 + display/d.graph/d.graph.md | 178 ++ display/d.grid/d.grid.md | 80 + display/d.his/d.his.md | 105 ++ display/d.histogram/d.histogram.md | 64 + display/d.info/d.info.md | 30 + display/d.labels/d.labels.md | 33 + display/d.legend.vect/d.legend.vect.md | 105 ++ display/d.legend/d.legend.md | 153 ++ display/d.linegraph/d.linegraph.md | 146 ++ display/d.mon/d.mon.md | 151 ++ display/d.northarrow/d.northarrow.md | 37 + display/d.path/d.path.md | 47 + display/d.profile/d.profile.md | 14 + display/d.rast.arrow/d.rast.arrow.md | 103 ++ display/d.rast.num/d.rast.num.md | 52 + display/d.rast/d.rast.md | 60 + display/d.redraw/d.redraw.md | 14 + display/d.rgb/d.rgb.md | 68 + display/d.rhumbline/d.rhumbline.md | 45 + display/d.text/d.text.md | 79 + display/d.title/d.title.md | 48 + display/d.vect.chart/d.vect.chart.md | 84 + display/d.vect.thematic/d.vect.thematic.md | 95 + display/d.vect/d.vect.md | 133 ++ display/d.where/d.where.md | 58 + display/displaydrivers.md | 63 + doc/grass_database.md | 206 +++ doc/gui/wxpython/example/g.gui.example.md | 36 + doc/projectionintro.md | 77 + doc/python/script/r.example.md | 29 + doc/raster/r.example/r.example.md | 29 + doc/vector/v.example/v.example.md | 28 + general/g.access/g.access.md | 39 + general/g.cairocomp/g.cairocomp.md | 14 + general/g.copy/g.copy.md | 77 + general/g.dirseps/g.dirseps.md | 9 + general/g.filename/g.filename.md | 58 + general/g.findetc/g.findetc.md | 22 + general/g.findfile/g.findfile.md | 97 + general/g.gisenv/g.gisenv.md | 186 ++ general/g.gui/g.gui.md | 67 + general/g.list/g.list.md | 212 +++ general/g.mapset/g.mapset.md | 69 + general/g.mapsets/g.mapsets.md | 181 ++ general/g.message/g.message.md | 138 ++ general/g.mkfontcap/g.mkfontcap.md | 56 + general/g.parser/g.parser.md | 665 +++++++ general/g.pnmcomp/g.pnmcomp.md | 36 + general/g.ppmtopng/g.ppmtopng.md | 8 + general/g.proj/g.proj.md | 246 +++ general/g.region/g.region.md | 403 +++++ general/g.remove/g.remove.md | 37 + general/g.rename/g.rename.md | 60 + general/g.setproj/g.setproj.md | 78 + general/g.tempfile/g.tempfile.md | 44 + general/g.version/g.version.md | 87 + gui/wxguiintro.md | 62 + gui/wxpython/animation/g.gui.animation.md | 89 + gui/wxpython/datacatalog/g.gui.datacatalog.md | 48 + gui/wxpython/dbmgr/g.gui.dbmgr.md | 55 + gui/wxpython/docs/wxGUI.components.md | 42 + gui/wxpython/docs/wxGUI.iscatt.md | 77 + gui/wxpython/docs/wxGUI.md | 598 +++++++ gui/wxpython/docs/wxGUI.modules.md | 179 ++ gui/wxpython/docs/wxGUI.nviz.md | 377 ++++ gui/wxpython/docs/wxGUI.toolboxes.md | 198 ++ gui/wxpython/docs/wxGUI.vnet.md | 89 + gui/wxpython/gcp/g.gui.gcp.md | 261 +++ gui/wxpython/gmodeler/g.gui.gmodeler.md | 388 ++++ gui/wxpython/iclass/g.gui.iclass.md | 77 + .../image2target/g.gui.image2target.md | 261 +++ gui/wxpython/mapswipe/g.gui.mapswipe.md | 44 + gui/wxpython/photo2image/g.gui.photo2image.md | 58 + gui/wxpython/psmap/g.gui.psmap.md | 193 ++ gui/wxpython/rdigit/g.gui.rdigit.md | 86 + gui/wxpython/rlisetup/g.gui.rlisetup.md | 263 +++ gui/wxpython/timeline/g.gui.timeline.md | 30 + gui/wxpython/tplot/g.gui.tplot.md | 91 + gui/wxpython/vdigit/g.gui.vdigit.md | 249 +++ imagery/i.albedo/i.albedo.md | 58 + imagery/i.aster.toar/i.aster.toar.md | 40 + imagery/i.atcorr/i.atcorr.md | 1112 ++++++++++++ imagery/i.biomass/i.biomass.md | 44 + imagery/i.cca/i.cca.md | 59 + imagery/i.cluster/i.cluster.md | 251 +++ imagery/i.eb.eta/i.eb.eta.md | 48 + imagery/i.eb.evapfr/i.eb.evapfr.md | 41 + imagery/i.eb.hsebal01/i.eb.hsebal01.md | 60 + imagery/i.eb.netrad/i.eb.netrad.md | 42 + .../i.eb.soilheatflux/i.eb.soilheatflux.md | 59 + imagery/i.emissivity/i.emissivity.md | 40 + imagery/i.evapo.mh/i.evapo.mh.md | 28 + imagery/i.evapo.pm/i.evapo.pm.md | 83 + imagery/i.evapo.pt/i.evapo.pt.md | 34 + imagery/i.evapo.time/i.evapo.time.md | 73 + imagery/i.fft/i.fft.md | 56 + imagery/i.gensig/i.gensig.md | 106 ++ imagery/i.gensigset/i.gensigset.md | 161 ++ imagery/i.group/i.group.md | 44 + imagery/i.his.rgb/i.his.rgb.md | 31 + imagery/i.ifft/i.ifft.md | 41 + imagery/i.landsat.acca/i.landsat.acca.md | 52 + imagery/i.landsat.toar/i.landsat.toar.md | 255 +++ imagery/i.maxlik/i.maxlik.md | 115 ++ imagery/i.modis.qc/i.modis.qc.md | 501 ++++++ .../i.ortho.camera/i.ortho.camera.md | 101 ++ .../i.ortho.elev/i.ortho.elev.md | 23 + .../i.ortho.init/i.ortho.init.md | 99 + .../i.ortho.photo/i.ortho.photo.md | 328 ++++ .../i.ortho.rectify/i.ortho.rectify.md | 110 ++ .../i.ortho.target/i.ortho.target.md | 17 + .../i.ortho.transform/i.ortho.transform.md | 35 + imagery/i.pca/i.pca.md | 102 ++ imagery/i.rectify/i.rectify.md | 169 ++ imagery/i.rgb.his/i.rgb.his.md | 20 + imagery/i.segment/i.segment.md | 272 +++ imagery/i.signatures/i.signatures.md | 58 + imagery/i.smap/i.smap.md | 192 ++ imagery/i.svm.predict/i.svm.predict.md | 70 + imagery/i.svm.train/i.svm.train.md | 100 ++ imagery/i.target/i.target.md | 33 + imagery/i.topo.corr/i.topo.corr.md | 114 ++ imagery/i.vi/i.vi.md | 551 ++++++ imagery/i.zc/i.zc.md | 52 + imagery/imageryintro.md | 266 +++ lib/cairodriver/cairodriver.md | 162 ++ lib/db/dbmi_base/test/test.dbmi_base.lib.md | 2 + lib/db/sqlp/sql.md | 214 +++ lib/gmath/test/test.gmath.lib.md | 1 + lib/gpde/test/test.gpde.lib.md | 9 + lib/htmldriver/htmldriver.md | 162 ++ lib/init/grass.md | 471 +++++ lib/init/helptext.md | 84 + lib/init/variables.md | 571 ++++++ lib/pngdriver/pngdriver.md | 93 + lib/psdriver/psdriver.md | 79 + lib/raster3d/test/test.raster3d.lib.md | 9 + lib/vector/rtree/test_suite/test.rtree.lib.md | 0 lib/vector/vectorascii.md | 131 ++ man/mkdocs/overrides/partials/footer.md | 71 + misc/m.cogo/m.cogo.md | 140 ++ misc/m.measure/m.measure.md | 57 + misc/m.nviz.image/m.nviz.image.md | 31 + misc/m.nviz.script/m.nviz.script.md | 149 ++ misc/m.transform/m.transform.md | 71 + mswindows/README.md | 3 + mswindows/external/rbatch/README.md | 8 + ps/ps.map/ps.map.md | 1587 +++++++++++++++++ python/grass/docs/_templates/oholosidebar.md | 0 raster/r.basins.fill/r.basins.fill.md | 38 + raster/r.buffer/r.buffer.md | 110 ++ raster/r.buildvrt/r.buildvrt.md | 74 + raster/r.carve/r.carve.md | 132 ++ raster/r.category/r.category.md | 196 ++ raster/r.circle/r.circle.md | 49 + raster/r.clump/r.clump.md | 114 ++ raster/r.coin/r.coin.md | 156 ++ raster/r.colors.out/r.colors.out.md | 20 + raster/r.colors.out/r3.colors.out.md | 22 + raster/r.colors/r.colors.md | 277 +++ raster/r.colors/r3.colors.md | 28 + raster/r.composite/r.composite.md | 50 + raster/r.compress/r.compress.md | 238 +++ raster/r.contour/r.contour.md | 73 + raster/r.cost/r.cost.md | 292 +++ raster/r.covar/r.covar.md | 75 + raster/r.cross/r.cross.md | 81 + raster/r.describe/r.describe.md | 92 + raster/r.distance/r.distance.md | 66 + raster/r.drain/r.drain.md | 297 +++ raster/r.external.out/r.external.out.md | 82 + raster/r.external/r.external.md | 77 + raster/r.fill.dir/r.fill.dir.md | 160 ++ raster/r.fill.stats/r.fill.stats.md | 375 ++++ raster/r.flow/r.flow.md | 182 ++ raster/r.geomorphon/r.geomorphon.md | 258 +++ raster/r.grow.distance/r.grow.distance.md | 123 ++ raster/r.gwflow/r.gwflow.md | 158 ++ raster/r.his/r.his.md | 105 ++ raster/r.horizon/r.horizon.md | 280 +++ raster/r.in.ascii/r.in.ascii.md | 97 + raster/r.in.bin/r.in.bin.md | 148 ++ raster/r.in.gdal/r.in.gdal.md | 397 +++++ raster/r.in.gridatb/r.in.gridatb.md | 12 + raster/r.in.lidar/r.in.lidar.md | 556 ++++++ raster/r.in.mat/r.in.mat.md | 121 ++ raster/r.in.pdal/r.in.pdal.md | 593 ++++++ raster/r.in.png/r.in.png.md | 20 + raster/r.in.poly/r.in.poly.md | 85 + raster/r.in.xyz/r.in.xyz.md | 310 ++++ raster/r.info/r.info.md | 178 ++ raster/r.kappa/r.kappa.md | 143 ++ raster/r.lake/r.lake.md | 105 ++ raster/r.latlong/r.latlong.md | 28 + raster/r.li/r.li.cwed/r.li.cwed.md | 80 + raster/r.li/r.li.daemon/r.li.daemon.md | 99 + raster/r.li/r.li.dominance/r.li.dominance.md | 74 + .../r.li/r.li.edgedensity/r.li.edgedensity.md | 93 + raster/r.li/r.li.md | 193 ++ raster/r.li/r.li.mpa/r.li.mpa.md | 86 + raster/r.li/r.li.mps/r.li.mps.md | 80 + raster/r.li/r.li.padcv/r.li.padcv.md | 74 + raster/r.li/r.li.padrange/r.li.padrange.md | 76 + raster/r.li/r.li.padsd/r.li.padsd.md | 75 + .../r.li.patchdensity/r.li.patchdensity.md | 86 + raster/r.li/r.li.patchnum/r.li.patchnum.md | 69 + raster/r.li/r.li.pielou/r.li.pielou.md | 72 + raster/r.li/r.li.renyi/r.li.renyi.md | 75 + raster/r.li/r.li.richness/r.li.richness.md | 70 + raster/r.li/r.li.shannon/r.li.shannon.md | 73 + raster/r.li/r.li.shape/r.li.shape.md | 75 + raster/r.li/r.li.simpson/r.li.simpson.md | 73 + raster/r.mapcalc/r.mapcalc.md | 939 ++++++++++ raster/r.mapcalc/r3.mapcalc.md | 708 ++++++++ raster/r.mask.status/r.mask.status.md | 69 + raster/r.mfilter/r.mfilter.md | 158 ++ raster/r.mode/r.mode.md | 51 + raster/r.neighbors/r.neighbors.md | 446 +++++ raster/r.null/r.null.md | 80 + raster/r.object.geometry/r.object.geometry.md | 116 ++ raster/r.out.ascii/r.out.ascii.md | 46 + raster/r.out.bin/r.out.bin.md | 39 + raster/r.out.gdal/r.out.gdal.md | 381 ++++ raster/r.out.gridatb/r.out.gridatb.md | 12 + raster/r.out.mat/r.out.mat.md | 92 + raster/r.out.mpeg/r.out.mpeg.md | 92 + raster/r.out.png/r.out.png.md | 35 + raster/r.out.pov/r.out.pov.md | 63 + raster/r.out.ppm/r.out.ppm.md | 53 + raster/r.out.ppm3/r.out.ppm3.md | 30 + raster/r.out.vrml/r.out.vrml.md | 60 + raster/r.out.vtk/r.out.vtk.md | 123 ++ raster/r.param.scale/r.param.scale.md | 88 + raster/r.patch/r.patch.md | 210 +++ raster/r.path/r.path.md | 197 ++ raster/r.profile/r.profile.md | 232 +++ raster/r.proj/r.proj.md | 306 ++++ raster/r.quant/r.quant.md | 35 + raster/r.quantile/r.quantile.md | 49 + raster/r.random.cells/r.random.cells.md | 125 ++ raster/r.random.surface/r.random.surface.md | 178 ++ raster/r.random/r.random.md | 145 ++ raster/r.reclass/r.reclass.md | 231 +++ raster/r.recode/r.recode.md | 75 + raster/r.region/r.region.md | 48 + raster/r.regression.line/r.regression.line.md | 78 + .../r.regression.multi/r.regression.multi.md | 93 + raster/r.relief/r.relief.md | 119 ++ raster/r.report/r.report.md | 872 +++++++++ raster/r.resamp.bspline/r.resamp.bspline.md | 154 ++ raster/r.resamp.filter/r.resamp.filter.md | 122 ++ raster/r.resamp.interp/r.resamp.interp.md | 84 + raster/r.resamp.rst/r.resamp.rst.md | 172 ++ raster/r.resamp.stats/r.resamp.stats.md | 55 + raster/r.resample/r.resample.md | 44 + raster/r.rescale.eq/r.rescale.eq.md | 47 + raster/r.rescale/r.rescale.md | 47 + raster/r.ros/r.ros.md | 125 ++ .../r.series.accumulate.md | 156 ++ raster/r.series.interp/r.series.interp.md | 59 + raster/r.series/r.series.md | 252 +++ raster/r.sim/r.sim.sediment/r.sim.sediment.md | 90 + raster/r.sim/r.sim.water/r.sim.water.md | 250 +++ raster/r.slope.aspect/r.slope.aspect.md | 279 +++ .../r.solute.transport/r.solute.transport.md | 152 ++ raster/r.spread/r.spread.md | 125 ++ raster/r.spreadpath/r.spreadpath.md | 59 + raster/r.statistics/r.statistics.md | 67 + raster/r.stats.quantile/r.stats.quantile.md | 60 + raster/r.stats.zonal/r.stats.zonal.md | 63 + raster/r.stats/r.stats.md | 175 ++ raster/r.stream.extract/r.stream.extract.md | 254 +++ raster/r.sun/r.sun.md | 356 ++++ raster/r.sunhours/r.sunhours.md | 75 + raster/r.sunmask/r.sunmask.md | 126 ++ raster/r.support.stats/r.support.stats.md | 17 + raster/r.support/r.support.md | 87 + raster/r.surf.area/r.surf.area.md | 67 + raster/r.surf.contour/r.surf.contour.md | 100 ++ raster/r.surf.fractal/r.surf.fractal.md | 76 + raster/r.surf.gauss/r.surf.gauss.md | 48 + raster/r.surf.idw/r.surf.idw.md | 90 + raster/r.surf.random/r.surf.random.md | 50 + raster/r.terraflow/r.terraflow.md | 241 +++ raster/r.texture/r.texture.md | 317 ++++ raster/r.thin/r.thin.md | 97 + raster/r.tile/r.tile.md | 38 + raster/r.timestamp/r.timestamp.md | 136 ++ raster/r.to.rast3/r.to.rast3.md | 56 + raster/r.to.rast3elev/r.to.rast3elev.md | 81 + raster/r.to.vect/r.to.vect.md | 130 ++ raster/r.topidx/r.topidx.md | 63 + raster/r.topmodel/r.topmodel.md | 153 ++ raster/r.transect/r.transect.md | 33 + raster/r.univar/r.univar.md | 291 +++ raster/r.univar/r3.univar.md | 101 ++ raster/r.uslek/r.uslek.md | 65 + raster/r.usler/r.usler.md | 22 + raster/r.viewshed/r.viewshed.md | 196 ++ raster/r.volume/r.volume.md | 142 ++ raster/r.walk/r.walk.md | 194 ++ raster/r.water.outlet/r.water.outlet.md | 61 + raster/r.watershed/front/r.watershed.md | 479 +++++ raster/r.what.color/r.what.color.md | 66 + raster/r.what/r.what.md | 186 ++ raster/rasterintro.md | 326 ++++ raster3d/r3.cross.rast/r3.cross.rast.md | 61 + raster3d/r3.flow/r3.flow.md | 111 ++ raster3d/r3.flow/test.r3flow.md | 11 + raster3d/r3.gradient/r3.gradient.md | 26 + raster3d/r3.gwflow/r3.gwflow.md | 143 ++ raster3d/r3.in.ascii/r3.in.ascii.md | 105 ++ raster3d/r3.in.bin/r3.in.bin.md | 50 + raster3d/r3.in.lidar/r3.in.lidar.md | 174 ++ raster3d/r3.in.v5d/r3.in.v5d.md | 21 + raster3d/r3.info/r3.info.md | 12 + raster3d/r3.mask/r3.mask.md | 20 + raster3d/r3.mkdspf/r3.mkdspf.md | 65 + raster3d/r3.neighbors/r3.neighbors.md | 83 + raster3d/r3.null/r3.null.md | 12 + raster3d/r3.out.ascii/r3.out.ascii.md | 202 +++ raster3d/r3.out.bin/r3.out.bin.md | 31 + raster3d/r3.out.netcdf/r3.out.netcdf.md | 267 +++ raster3d/r3.out.v5d/r3.out.v5d.md | 22 + raster3d/r3.out.vtk/r3.out.vtk.md | 170 ++ raster3d/r3.retile/r3.retile.md | 15 + raster3d/r3.showdspf/r3.showdspf.md | 142 ++ .../r3.showdspf/r3.showdspf_opengl_mods.md | 52 + raster3d/r3.stats/r3.stats.md | 98 + raster3d/r3.support/r3.support.md | 22 + raster3d/r3.timestamp/r3.timestamp.md | 68 + raster3d/r3.to.rast/r3.to.rast.md | 63 + raster3d/raster3dintro.md | 181 ++ scripts/d.background/d.background.md | 38 + scripts/d.correlate/d.correlate.md | 41 + scripts/d.frame/d.frame.md | 83 + scripts/d.out.file/d.out.file.md | 15 + scripts/d.polar/d.polar.md | 68 + scripts/d.rast.edit/d.rast.edit.md | 122 ++ scripts/d.rast.leg/d.rast.leg.md | 45 + scripts/d.shade/d.shade.md | 61 + scripts/d.to.rast/d.to.rast.md | 41 + scripts/d.what.rast/d.what.rast.md | 16 + scripts/d.what.vect/d.what.vect.md | 16 + scripts/db.dropcolumn/db.dropcolumn.md | 39 + scripts/db.droptable/db.droptable.md | 54 + scripts/db.in.ogr/db.in.ogr.md | 71 + scripts/db.out.ogr/db.out.ogr.md | 48 + scripts/db.test/db.test.md | 22 + scripts/db.univar/db.univar.md | 35 + .../g.download.location.md | 14 + .../g.download.project/g.download.project.md | 39 + scripts/g.extension.all/g.extension.all.md | 32 + scripts/g.extension/g.extension.md | 271 +++ .../r.plus.example/r.plus.example.md | 19 + scripts/g.manual/g.manual.md | 34 + scripts/g.search.modules/g.search.modules.md | 77 + scripts/i.band.library/i.band.library.md | 263 +++ scripts/i.colors.enhance/i.colors.enhance.md | 67 + scripts/i.image.mosaic/i.image.mosaic.md | 13 + scripts/i.in.spotvgt/i.in.spotvgt.md | 53 + scripts/i.oif/i.oif.md | 67 + scripts/i.pansharpen/i.pansharpen.md | 249 +++ scripts/i.spectral/i.spectral.md | 47 + scripts/i.tasscap/i.tasscap.md | 104 ++ scripts/m.proj/m.proj.md | 199 +++ scripts/r.blend/r.blend.md | 34 + scripts/r.buffer.lowmem/r.buffer.lowmem.md | 51 + scripts/r.colors.stddev/r.colors.stddev.md | 41 + scripts/r.drain/r.drain.md | 297 +++ scripts/r.fillnulls/r.fillnulls.md | 125 ++ scripts/r.grow/r.grow.md | 91 + scripts/r.import/r.import.md | 144 ++ scripts/r.in.aster/r.in.aster.md | 25 + scripts/r.in.srtm/r.in.srtm.md | 52 + scripts/r.in.wms/r.in.wms.md | 180 ++ scripts/r.mapcalc.simple/r.mapcalc.simple.md | 105 ++ scripts/r.mask/r.mask.md | 145 ++ scripts/r.out.xyz/r.out.xyz.md | 66 + scripts/r.pack/r.pack.md | 40 + scripts/r.plane/r.plane.md | 54 + scripts/r.reclass.area/r.reclass.area.md | 58 + scripts/r.rgb/r.rgb.md | 25 + scripts/r.semantic.label/r.semantic.label.md | 84 + scripts/r.shade/r.shade.md | 80 + scripts/r.tileset/r.tileset.md | 91 + scripts/r.unpack/r.unpack.md | 34 + scripts/r3.in.xyz/r3.in.xyz.md | 78 + scripts/v.build.all/v.build.all.md | 15 + scripts/v.centroids/v.centroids.md | 47 + scripts/v.clip/v.clip.md | 71 + scripts/v.db.addcolumn/v.db.addcolumn.md | 45 + scripts/v.db.addtable/v.db.addtable.md | 59 + scripts/v.db.dropcolumn/v.db.dropcolumn.md | 36 + scripts/v.db.droprow/v.db.droprow.md | 48 + scripts/v.db.droptable/v.db.droptable.md | 35 + scripts/v.db.join/v.db.join.md | 113 ++ .../v.db.reconnect.all/v.db.reconnect.all.md | 114 ++ .../v.db.renamecolumn/v.db.renamecolumn.md | 46 + scripts/v.db.univar/v.db.univar.md | 81 + scripts/v.db.update/v.db.update.md | 103 ++ scripts/v.dissolve/v.dissolve.md | 327 ++++ scripts/v.import/v.import.md | 71 + scripts/v.in.e00/v.in.e00.md | 26 + scripts/v.in.geonames/v.in.geonames.md | 71 + scripts/v.in.lines/v.in.lines.md | 45 + scripts/v.in.mapgen/v.in.mapgen.md | 32 + scripts/v.in.wfs/v.in.wfs.md | 56 + scripts/v.pack/v.pack.md | 34 + scripts/v.rast.stats/v.rast.stats.md | 83 + scripts/v.report/v.report.md | 36 + scripts/v.to.lines/v.to.lines.md | 39 + scripts/v.unpack/v.unpack.md | 30 + scripts/v.what.strds/v.what.strds.md | 23 + scripts/v.what.vect/v.what.vect.md | 75 + scripts/wxpyimgview/wxpyimgview.md | 19 + temporal/t.connect/t.connect.md | 64 + temporal/t.copy/t.copy.md | 37 + temporal/t.create/t.create.md | 50 + temporal/t.info/t.info.md | 173 ++ temporal/t.list/t.list.md | 90 + temporal/t.merge/t.merge.md | 222 +++ temporal/t.rast.accdetect/t.rast.accdetect.md | 74 + .../t.rast.accumulate/t.rast.accumulate.md | 283 +++ .../t.rast.aggregate.ds.md | 357 ++++ temporal/t.rast.aggregate/t.rast.aggregate.md | 202 +++ temporal/t.rast.algebra/t.rast.algebra.md | 633 +++++++ temporal/t.rast.colors/t.rast.colors.md | 64 + temporal/t.rast.contour/t.rast.contour.md | 36 + temporal/t.rast.export/t.rast.export.md | 139 ++ temporal/t.rast.extract/t.rast.extract.md | 57 + temporal/t.rast.gapfill/t.rast.gapfill.md | 83 + temporal/t.rast.import/t.rast.import.md | 35 + temporal/t.rast.list/t.rast.list.md | 239 +++ temporal/t.rast.mapcalc/t.rast.mapcalc.md | 181 ++ temporal/t.rast.neighbors/t.rast.neighbors.md | 120 ++ temporal/t.rast.out.vtk/t.rast.out.vtk.md | 41 + temporal/t.rast.series/t.rast.series.md | 102 ++ temporal/t.rast.to.rast3/t.rast.to.rast3.md | 161 ++ temporal/t.rast.to.vect/t.rast.to.vect.md | 36 + temporal/t.rast.univar/t.rast.univar.md | 55 + temporal/t.rast.what/t.rast.what.md | 127 ++ temporal/t.rast3d.algebra/t.rast3d.algebra.md | 31 + temporal/t.rast3d.extract/t.rast3d.extract.md | 19 + temporal/t.rast3d.list/t.rast3d.list.md | 16 + temporal/t.rast3d.mapcalc/t.rast3d.mapcalc.md | 17 + temporal/t.rast3d.univar/t.rast3d.univar.md | 16 + temporal/t.register/t.register.md | 319 ++++ temporal/t.remove/t.remove.md | 56 + temporal/t.rename/t.rename.md | 35 + temporal/t.sample/t.sample.md | 171 ++ temporal/t.select/t.select.md | 398 +++++ temporal/t.shift/t.shift.md | 194 ++ temporal/t.snap/t.snap.md | 195 ++ temporal/t.support/t.support.md | 39 + temporal/t.topology/t.topology.md | 50 + temporal/t.unregister/t.unregister.md | 60 + temporal/t.upgrade/t.upgrade.md | 20 + temporal/t.vect.algebra/t.vect.algebra.md | 442 +++++ temporal/t.vect.db.select/t.vect.db.select.md | 49 + temporal/t.vect.export/t.vect.export.md | 125 ++ temporal/t.vect.extract/t.vect.extract.md | 85 + temporal/t.vect.import/t.vect.import.md | 64 + temporal/t.vect.list/t.vect.list.md | 62 + .../t.vect.observe.strds.md | 136 ++ temporal/t.vect.univar/t.vect.univar.md | 30 + .../t.vect.what.strds/t.vect.what.strds.md | 30 + temporal/temporalintro.md | 262 +++ vector/v.buffer/v.buffer.md | 140 ++ vector/v.build.polylines/v.build.polylines.md | 75 + vector/v.build/v.build.md | 75 + vector/v.category/v.category.md | 140 ++ vector/v.class/v.class.md | 86 + vector/v.clean/test/description.md | 11 + vector/v.clean/v.clean.md | 321 ++++ vector/v.cluster/v.cluster.md | 156 ++ vector/v.colors.out/v.colors.out.md | 21 + vector/v.colors/v.colors.md | 144 ++ vector/v.db.connect/v.db.connect.md | 200 +++ vector/v.db.select/v.db.select.md | 346 ++++ vector/v.decimate/v.decimate.md | 107 ++ vector/v.delaunay/v.delaunay.md | 38 + vector/v.distance/v.distance.md | 229 +++ vector/v.drape/v.drape.md | 63 + vector/v.edit/v.edit.md | 415 +++++ vector/v.external.out/v.external.out.md | 190 ++ vector/v.external/v.external.md | 142 ++ vector/v.extract/v.extract.md | 132 ++ vector/v.extrude/v.extrude.md | 67 + vector/v.fill.holes/v.fill.holes.md | 106 ++ vector/v.generalize/v.generalize.md | 307 ++++ vector/v.hull/v.hull.md | 65 + vector/v.in.ascii/v.in.ascii.md | 319 ++++ vector/v.in.db/v.in.db.md | 137 ++ vector/v.in.dxf/v.in.dxf.md | 59 + vector/v.in.lidar/v.in.lidar.md | 140 ++ vector/v.in.ogr/v.in.ogr.md | 429 +++++ vector/v.in.pdal/v.in.pdal.md | 37 + vector/v.in.region/v.in.region.md | 30 + vector/v.info/v.info.md | 224 +++ vector/v.kcv/v.kcv.md | 57 + vector/v.kernel/v.kernel.md | 70 + vector/v.label.sa/v.label.sa.md | 46 + vector/v.label/v.label.md | 157 ++ .../v.lidar.correction/v.lidar.correction.md | 100 ++ .../v.lidar.edgedetection.md | 144 ++ vector/v.lidar.growing/v.lidar.growing.md | 85 + vector/v.lrs/lrs.md | 189 ++ vector/v.lrs/v.lrs.create/v.lrs.create.md | 156 ++ vector/v.lrs/v.lrs.label/v.lrs.label.md | 34 + vector/v.lrs/v.lrs.segment/v.lrs.segment.md | 57 + vector/v.lrs/v.lrs.where/v.lrs.where.md | 50 + vector/v.mkgrid/v.mkgrid.md | 175 ++ vector/v.neighbors/v.neighbors.md | 51 + vector/v.net.alloc/v.net.alloc.md | 226 +++ vector/v.net.allpairs/v.net.allpairs.md | 57 + vector/v.net.bridge/v.net.bridge.md | 33 + vector/v.net.centrality/v.net.centrality.md | 43 + vector/v.net.components/v.net.components.md | 47 + .../v.net.connectivity/v.net.connectivity.md | 40 + vector/v.net.distance/v.net.distance.md | 163 ++ vector/v.net.flow/v.net.flow.md | 53 + vector/v.net.iso/v.net.iso.md | 199 +++ vector/v.net.path/v.net.path.md | 188 ++ vector/v.net.salesman/v.net.salesman.md | 167 ++ .../v.net.spanningtree/v.net.spanningtree.md | 32 + vector/v.net.steiner/v.net.steiner.md | 130 ++ vector/v.net.timetable/v.net.timetable.md | 158 ++ vector/v.net.visibility/v.net.visibility.md | 213 +++ vector/v.net/v.net.md | 216 +++ vector/v.normal/v.normal.md | 52 + vector/v.out.ascii/v.out.ascii.md | 137 ++ vector/v.out.dxf/v.out.dxf.md | 29 + vector/v.out.lidar/v.out.lidar.md | 48 + vector/v.out.ogr/v.out.ogr.md | 193 ++ vector/v.out.postgis/v.out.postgis.md | 249 +++ vector/v.out.pov/v.out.pov.md | 29 + vector/v.out.svg/v.out.svg.md | 50 + vector/v.out.vtk/v.out.vtk.md | 89 + vector/v.outlier/v.outlier.md | 65 + vector/v.overlay/v.overlay.md | 228 +++ vector/v.parallel/v.parallel.md | 23 + vector/v.patch/v.patch.md | 60 + vector/v.perturb/v.perturb.md | 84 + vector/v.profile/v.profile.md | 87 + vector/v.proj/v.proj.md | 90 + vector/v.qcount/v.qcount.md | 110 ++ vector/v.random/v.random.md | 249 +++ vector/v.reclass/v.reclass.md | 84 + vector/v.rectify/v.rectify.md | 108 ++ vector/v.sample/v.sample.md | 69 + vector/v.segment/v.segment.md | 188 ++ vector/v.select/v.select.md | 281 +++ vector/v.split/v.split.md | 95 + vector/v.support/v.support.md | 24 + vector/v.surf.bspline/v.surf.bspline.md | 176 ++ vector/v.surf.idw/v.surf.idw.md | 89 + vector/v.surf.rst/v.surf.rst.md | 387 ++++ vector/v.timestamp/v.timestamp.md | 58 + vector/v.to.3d/v.to.3d.md | 48 + vector/v.to.db/v.to.db.md | 179 ++ vector/v.to.points/v.to.points.md | 118 ++ vector/v.to.rast/v.to.rast.md | 167 ++ vector/v.to.rast3/v.to.rast3.md | 26 + vector/v.transform/v.transform.md | 90 + vector/v.type/v.type.md | 42 + vector/v.univar/v.univar.md | 172 ++ vector/v.vect.stats/v.vect.stats.md | 205 +++ vector/v.vol.rst/v.vol.rst.md | 301 ++++ vector/v.voronoi/v.voronoi.md | 99 + vector/v.what.rast/v.what.rast.md | 105 ++ vector/v.what.rast3/v.what.rast3.md | 52 + vector/v.what/v.what.md | 36 + vector/vectorintro.md | 348 ++++ visualization/ximgview/ximgview.md | 39 + 603 files changed, 72741 insertions(+) create mode 100644 db/databaseintro.md create mode 100644 db/db.columns/db.columns.md create mode 100644 db/db.connect/db.connect.md create mode 100644 db/db.copy/db.copy.md create mode 100644 db/db.createdb/db.createdb.md create mode 100644 db/db.databases/db.databases.md create mode 100644 db/db.describe/db.describe.md create mode 100644 db/db.drivers/db.drivers.md create mode 100644 db/db.dropdb/db.dropdb.md create mode 100644 db/db.execute/db.execute.md create mode 100644 db/db.login/db.login.md create mode 100644 db/db.select/db.select.md create mode 100644 db/db.tables/db.tables.md create mode 100644 db/drivers/dbf/grass-dbf.md create mode 100644 db/drivers/mysql/grass-mesql.md create mode 100644 db/drivers/mysql/grass-mysql.md create mode 100644 db/drivers/odbc/grass-odbc.md create mode 100644 db/drivers/ogr/grass-ogr.md create mode 100644 db/drivers/postgres/grass-pg.md create mode 100644 db/drivers/sqlite/grass-sqlite.md create mode 100644 display/d.barscale/d.barscale.md create mode 100644 display/d.colorlist/d.colorlist.md create mode 100644 display/d.colortable/d.colortable.md create mode 100644 display/d.erase/d.erase.md create mode 100644 display/d.extract/d.extract.md create mode 100644 display/d.font/d.font.md create mode 100644 display/d.fontlist/d.fontlist.md create mode 100644 display/d.geodesic/d.geodesic.md create mode 100644 display/d.graph/d.graph.md create mode 100644 display/d.grid/d.grid.md create mode 100644 display/d.his/d.his.md create mode 100644 display/d.histogram/d.histogram.md create mode 100644 display/d.info/d.info.md create mode 100644 display/d.labels/d.labels.md create mode 100644 display/d.legend.vect/d.legend.vect.md create mode 100644 display/d.legend/d.legend.md create mode 100644 display/d.linegraph/d.linegraph.md create mode 100644 display/d.mon/d.mon.md create mode 100644 display/d.northarrow/d.northarrow.md create mode 100644 display/d.path/d.path.md create mode 100644 display/d.profile/d.profile.md create mode 100644 display/d.rast.arrow/d.rast.arrow.md create mode 100644 display/d.rast.num/d.rast.num.md create mode 100644 display/d.rast/d.rast.md create mode 100644 display/d.redraw/d.redraw.md create mode 100644 display/d.rgb/d.rgb.md create mode 100644 display/d.rhumbline/d.rhumbline.md create mode 100644 display/d.text/d.text.md create mode 100644 display/d.title/d.title.md create mode 100644 display/d.vect.chart/d.vect.chart.md create mode 100644 display/d.vect.thematic/d.vect.thematic.md create mode 100644 display/d.vect/d.vect.md create mode 100644 display/d.where/d.where.md create mode 100644 display/displaydrivers.md create mode 100644 doc/grass_database.md create mode 100644 doc/gui/wxpython/example/g.gui.example.md create mode 100644 doc/projectionintro.md create mode 100644 doc/python/script/r.example.md create mode 100644 doc/raster/r.example/r.example.md create mode 100644 doc/vector/v.example/v.example.md create mode 100644 general/g.access/g.access.md create mode 100644 general/g.cairocomp/g.cairocomp.md create mode 100644 general/g.copy/g.copy.md create mode 100644 general/g.dirseps/g.dirseps.md create mode 100644 general/g.filename/g.filename.md create mode 100644 general/g.findetc/g.findetc.md create mode 100644 general/g.findfile/g.findfile.md create mode 100644 general/g.gisenv/g.gisenv.md create mode 100644 general/g.gui/g.gui.md create mode 100644 general/g.list/g.list.md create mode 100644 general/g.mapset/g.mapset.md create mode 100644 general/g.mapsets/g.mapsets.md create mode 100644 general/g.message/g.message.md create mode 100644 general/g.mkfontcap/g.mkfontcap.md create mode 100644 general/g.parser/g.parser.md create mode 100644 general/g.pnmcomp/g.pnmcomp.md create mode 100644 general/g.ppmtopng/g.ppmtopng.md create mode 100644 general/g.proj/g.proj.md create mode 100644 general/g.region/g.region.md create mode 100644 general/g.remove/g.remove.md create mode 100644 general/g.rename/g.rename.md create mode 100644 general/g.setproj/g.setproj.md create mode 100644 general/g.tempfile/g.tempfile.md create mode 100644 general/g.version/g.version.md create mode 100644 gui/wxguiintro.md create mode 100644 gui/wxpython/animation/g.gui.animation.md create mode 100644 gui/wxpython/datacatalog/g.gui.datacatalog.md create mode 100644 gui/wxpython/dbmgr/g.gui.dbmgr.md create mode 100644 gui/wxpython/docs/wxGUI.components.md create mode 100644 gui/wxpython/docs/wxGUI.iscatt.md create mode 100644 gui/wxpython/docs/wxGUI.md create mode 100644 gui/wxpython/docs/wxGUI.modules.md create mode 100644 gui/wxpython/docs/wxGUI.nviz.md create mode 100644 gui/wxpython/docs/wxGUI.toolboxes.md create mode 100644 gui/wxpython/docs/wxGUI.vnet.md create mode 100644 gui/wxpython/gcp/g.gui.gcp.md create mode 100644 gui/wxpython/gmodeler/g.gui.gmodeler.md create mode 100644 gui/wxpython/iclass/g.gui.iclass.md create mode 100644 gui/wxpython/image2target/g.gui.image2target.md create mode 100644 gui/wxpython/mapswipe/g.gui.mapswipe.md create mode 100644 gui/wxpython/photo2image/g.gui.photo2image.md create mode 100644 gui/wxpython/psmap/g.gui.psmap.md create mode 100644 gui/wxpython/rdigit/g.gui.rdigit.md create mode 100644 gui/wxpython/rlisetup/g.gui.rlisetup.md create mode 100644 gui/wxpython/timeline/g.gui.timeline.md create mode 100644 gui/wxpython/tplot/g.gui.tplot.md create mode 100644 gui/wxpython/vdigit/g.gui.vdigit.md create mode 100644 imagery/i.albedo/i.albedo.md create mode 100644 imagery/i.aster.toar/i.aster.toar.md create mode 100644 imagery/i.atcorr/i.atcorr.md create mode 100644 imagery/i.biomass/i.biomass.md create mode 100644 imagery/i.cca/i.cca.md create mode 100644 imagery/i.cluster/i.cluster.md create mode 100644 imagery/i.eb.eta/i.eb.eta.md create mode 100644 imagery/i.eb.evapfr/i.eb.evapfr.md create mode 100644 imagery/i.eb.hsebal01/i.eb.hsebal01.md create mode 100644 imagery/i.eb.netrad/i.eb.netrad.md create mode 100644 imagery/i.eb.soilheatflux/i.eb.soilheatflux.md create mode 100644 imagery/i.emissivity/i.emissivity.md create mode 100644 imagery/i.evapo.mh/i.evapo.mh.md create mode 100644 imagery/i.evapo.pm/i.evapo.pm.md create mode 100644 imagery/i.evapo.pt/i.evapo.pt.md create mode 100644 imagery/i.evapo.time/i.evapo.time.md create mode 100644 imagery/i.fft/i.fft.md create mode 100644 imagery/i.gensig/i.gensig.md create mode 100644 imagery/i.gensigset/i.gensigset.md create mode 100644 imagery/i.group/i.group.md create mode 100644 imagery/i.his.rgb/i.his.rgb.md create mode 100644 imagery/i.ifft/i.ifft.md create mode 100644 imagery/i.landsat.acca/i.landsat.acca.md create mode 100644 imagery/i.landsat.toar/i.landsat.toar.md create mode 100644 imagery/i.maxlik/i.maxlik.md create mode 100644 imagery/i.modis.qc/i.modis.qc.md create mode 100644 imagery/i.ortho.photo/i.ortho.camera/i.ortho.camera.md create mode 100644 imagery/i.ortho.photo/i.ortho.elev/i.ortho.elev.md create mode 100644 imagery/i.ortho.photo/i.ortho.init/i.ortho.init.md create mode 100644 imagery/i.ortho.photo/i.ortho.photo/i.ortho.photo.md create mode 100644 imagery/i.ortho.photo/i.ortho.rectify/i.ortho.rectify.md create mode 100644 imagery/i.ortho.photo/i.ortho.target/i.ortho.target.md create mode 100644 imagery/i.ortho.photo/i.ortho.transform/i.ortho.transform.md create mode 100644 imagery/i.pca/i.pca.md create mode 100644 imagery/i.rectify/i.rectify.md create mode 100644 imagery/i.rgb.his/i.rgb.his.md create mode 100644 imagery/i.segment/i.segment.md create mode 100644 imagery/i.signatures/i.signatures.md create mode 100644 imagery/i.smap/i.smap.md create mode 100644 imagery/i.svm.predict/i.svm.predict.md create mode 100644 imagery/i.svm.train/i.svm.train.md create mode 100644 imagery/i.target/i.target.md create mode 100644 imagery/i.topo.corr/i.topo.corr.md create mode 100644 imagery/i.vi/i.vi.md create mode 100644 imagery/i.zc/i.zc.md create mode 100644 imagery/imageryintro.md create mode 100644 lib/cairodriver/cairodriver.md create mode 100644 lib/db/dbmi_base/test/test.dbmi_base.lib.md create mode 100644 lib/db/sqlp/sql.md create mode 100644 lib/gmath/test/test.gmath.lib.md create mode 100644 lib/gpde/test/test.gpde.lib.md create mode 100644 lib/htmldriver/htmldriver.md create mode 100644 lib/init/grass.md create mode 100644 lib/init/helptext.md create mode 100644 lib/init/variables.md create mode 100644 lib/pngdriver/pngdriver.md create mode 100644 lib/psdriver/psdriver.md create mode 100644 lib/raster3d/test/test.raster3d.lib.md create mode 100644 lib/vector/rtree/test_suite/test.rtree.lib.md create mode 100644 lib/vector/vectorascii.md create mode 100644 man/mkdocs/overrides/partials/footer.md create mode 100644 misc/m.cogo/m.cogo.md create mode 100644 misc/m.measure/m.measure.md create mode 100644 misc/m.nviz.image/m.nviz.image.md create mode 100644 misc/m.nviz.script/m.nviz.script.md create mode 100644 misc/m.transform/m.transform.md create mode 100644 mswindows/README.md create mode 100644 mswindows/external/rbatch/README.md create mode 100644 ps/ps.map/ps.map.md create mode 100644 python/grass/docs/_templates/oholosidebar.md create mode 100644 raster/r.basins.fill/r.basins.fill.md create mode 100644 raster/r.buffer/r.buffer.md create mode 100644 raster/r.buildvrt/r.buildvrt.md create mode 100644 raster/r.carve/r.carve.md create mode 100644 raster/r.category/r.category.md create mode 100644 raster/r.circle/r.circle.md create mode 100644 raster/r.clump/r.clump.md create mode 100644 raster/r.coin/r.coin.md create mode 100644 raster/r.colors.out/r.colors.out.md create mode 100644 raster/r.colors.out/r3.colors.out.md create mode 100644 raster/r.colors/r.colors.md create mode 100644 raster/r.colors/r3.colors.md create mode 100644 raster/r.composite/r.composite.md create mode 100644 raster/r.compress/r.compress.md create mode 100644 raster/r.contour/r.contour.md create mode 100644 raster/r.cost/r.cost.md create mode 100644 raster/r.covar/r.covar.md create mode 100644 raster/r.cross/r.cross.md create mode 100644 raster/r.describe/r.describe.md create mode 100644 raster/r.distance/r.distance.md create mode 100644 raster/r.drain/r.drain.md create mode 100644 raster/r.external.out/r.external.out.md create mode 100644 raster/r.external/r.external.md create mode 100644 raster/r.fill.dir/r.fill.dir.md create mode 100644 raster/r.fill.stats/r.fill.stats.md create mode 100644 raster/r.flow/r.flow.md create mode 100644 raster/r.geomorphon/r.geomorphon.md create mode 100644 raster/r.grow.distance/r.grow.distance.md create mode 100644 raster/r.gwflow/r.gwflow.md create mode 100644 raster/r.his/r.his.md create mode 100644 raster/r.horizon/r.horizon.md create mode 100644 raster/r.in.ascii/r.in.ascii.md create mode 100644 raster/r.in.bin/r.in.bin.md create mode 100644 raster/r.in.gdal/r.in.gdal.md create mode 100644 raster/r.in.gridatb/r.in.gridatb.md create mode 100644 raster/r.in.lidar/r.in.lidar.md create mode 100644 raster/r.in.mat/r.in.mat.md create mode 100644 raster/r.in.pdal/r.in.pdal.md create mode 100644 raster/r.in.png/r.in.png.md create mode 100644 raster/r.in.poly/r.in.poly.md create mode 100644 raster/r.in.xyz/r.in.xyz.md create mode 100644 raster/r.info/r.info.md create mode 100644 raster/r.kappa/r.kappa.md create mode 100644 raster/r.lake/r.lake.md create mode 100644 raster/r.latlong/r.latlong.md create mode 100644 raster/r.li/r.li.cwed/r.li.cwed.md create mode 100644 raster/r.li/r.li.daemon/r.li.daemon.md create mode 100644 raster/r.li/r.li.dominance/r.li.dominance.md create mode 100644 raster/r.li/r.li.edgedensity/r.li.edgedensity.md create mode 100644 raster/r.li/r.li.md create mode 100644 raster/r.li/r.li.mpa/r.li.mpa.md create mode 100644 raster/r.li/r.li.mps/r.li.mps.md create mode 100644 raster/r.li/r.li.padcv/r.li.padcv.md create mode 100644 raster/r.li/r.li.padrange/r.li.padrange.md create mode 100644 raster/r.li/r.li.padsd/r.li.padsd.md create mode 100644 raster/r.li/r.li.patchdensity/r.li.patchdensity.md create mode 100644 raster/r.li/r.li.patchnum/r.li.patchnum.md create mode 100644 raster/r.li/r.li.pielou/r.li.pielou.md create mode 100644 raster/r.li/r.li.renyi/r.li.renyi.md create mode 100644 raster/r.li/r.li.richness/r.li.richness.md create mode 100644 raster/r.li/r.li.shannon/r.li.shannon.md create mode 100644 raster/r.li/r.li.shape/r.li.shape.md create mode 100644 raster/r.li/r.li.simpson/r.li.simpson.md create mode 100644 raster/r.mapcalc/r.mapcalc.md create mode 100644 raster/r.mapcalc/r3.mapcalc.md create mode 100644 raster/r.mask.status/r.mask.status.md create mode 100644 raster/r.mfilter/r.mfilter.md create mode 100644 raster/r.mode/r.mode.md create mode 100644 raster/r.neighbors/r.neighbors.md create mode 100644 raster/r.null/r.null.md create mode 100644 raster/r.object.geometry/r.object.geometry.md create mode 100644 raster/r.out.ascii/r.out.ascii.md create mode 100644 raster/r.out.bin/r.out.bin.md create mode 100644 raster/r.out.gdal/r.out.gdal.md create mode 100644 raster/r.out.gridatb/r.out.gridatb.md create mode 100644 raster/r.out.mat/r.out.mat.md create mode 100644 raster/r.out.mpeg/r.out.mpeg.md create mode 100644 raster/r.out.png/r.out.png.md create mode 100644 raster/r.out.pov/r.out.pov.md create mode 100644 raster/r.out.ppm/r.out.ppm.md create mode 100644 raster/r.out.ppm3/r.out.ppm3.md create mode 100644 raster/r.out.vrml/r.out.vrml.md create mode 100644 raster/r.out.vtk/r.out.vtk.md create mode 100644 raster/r.param.scale/r.param.scale.md create mode 100644 raster/r.patch/r.patch.md create mode 100644 raster/r.path/r.path.md create mode 100644 raster/r.profile/r.profile.md create mode 100644 raster/r.proj/r.proj.md create mode 100644 raster/r.quant/r.quant.md create mode 100644 raster/r.quantile/r.quantile.md create mode 100644 raster/r.random.cells/r.random.cells.md create mode 100644 raster/r.random.surface/r.random.surface.md create mode 100644 raster/r.random/r.random.md create mode 100644 raster/r.reclass/r.reclass.md create mode 100644 raster/r.recode/r.recode.md create mode 100644 raster/r.region/r.region.md create mode 100644 raster/r.regression.line/r.regression.line.md create mode 100644 raster/r.regression.multi/r.regression.multi.md create mode 100644 raster/r.relief/r.relief.md create mode 100644 raster/r.report/r.report.md create mode 100644 raster/r.resamp.bspline/r.resamp.bspline.md create mode 100644 raster/r.resamp.filter/r.resamp.filter.md create mode 100644 raster/r.resamp.interp/r.resamp.interp.md create mode 100644 raster/r.resamp.rst/r.resamp.rst.md create mode 100644 raster/r.resamp.stats/r.resamp.stats.md create mode 100644 raster/r.resample/r.resample.md create mode 100644 raster/r.rescale.eq/r.rescale.eq.md create mode 100644 raster/r.rescale/r.rescale.md create mode 100644 raster/r.ros/r.ros.md create mode 100644 raster/r.series.accumulate/r.series.accumulate.md create mode 100644 raster/r.series.interp/r.series.interp.md create mode 100644 raster/r.series/r.series.md create mode 100644 raster/r.sim/r.sim.sediment/r.sim.sediment.md create mode 100644 raster/r.sim/r.sim.water/r.sim.water.md create mode 100644 raster/r.slope.aspect/r.slope.aspect.md create mode 100644 raster/r.solute.transport/r.solute.transport.md create mode 100644 raster/r.spread/r.spread.md create mode 100644 raster/r.spreadpath/r.spreadpath.md create mode 100644 raster/r.statistics/r.statistics.md create mode 100644 raster/r.stats.quantile/r.stats.quantile.md create mode 100644 raster/r.stats.zonal/r.stats.zonal.md create mode 100644 raster/r.stats/r.stats.md create mode 100644 raster/r.stream.extract/r.stream.extract.md create mode 100644 raster/r.sun/r.sun.md create mode 100644 raster/r.sunhours/r.sunhours.md create mode 100644 raster/r.sunmask/r.sunmask.md create mode 100644 raster/r.support.stats/r.support.stats.md create mode 100644 raster/r.support/r.support.md create mode 100644 raster/r.surf.area/r.surf.area.md create mode 100644 raster/r.surf.contour/r.surf.contour.md create mode 100644 raster/r.surf.fractal/r.surf.fractal.md create mode 100644 raster/r.surf.gauss/r.surf.gauss.md create mode 100644 raster/r.surf.idw/r.surf.idw.md create mode 100644 raster/r.surf.random/r.surf.random.md create mode 100644 raster/r.terraflow/r.terraflow.md create mode 100644 raster/r.texture/r.texture.md create mode 100644 raster/r.thin/r.thin.md create mode 100644 raster/r.tile/r.tile.md create mode 100644 raster/r.timestamp/r.timestamp.md create mode 100644 raster/r.to.rast3/r.to.rast3.md create mode 100644 raster/r.to.rast3elev/r.to.rast3elev.md create mode 100644 raster/r.to.vect/r.to.vect.md create mode 100644 raster/r.topidx/r.topidx.md create mode 100644 raster/r.topmodel/r.topmodel.md create mode 100644 raster/r.transect/r.transect.md create mode 100644 raster/r.univar/r.univar.md create mode 100644 raster/r.univar/r3.univar.md create mode 100644 raster/r.uslek/r.uslek.md create mode 100644 raster/r.usler/r.usler.md create mode 100644 raster/r.viewshed/r.viewshed.md create mode 100644 raster/r.volume/r.volume.md create mode 100644 raster/r.walk/r.walk.md create mode 100644 raster/r.water.outlet/r.water.outlet.md create mode 100644 raster/r.watershed/front/r.watershed.md create mode 100644 raster/r.what.color/r.what.color.md create mode 100644 raster/r.what/r.what.md create mode 100644 raster/rasterintro.md create mode 100644 raster3d/r3.cross.rast/r3.cross.rast.md create mode 100644 raster3d/r3.flow/r3.flow.md create mode 100644 raster3d/r3.flow/test.r3flow.md create mode 100644 raster3d/r3.gradient/r3.gradient.md create mode 100644 raster3d/r3.gwflow/r3.gwflow.md create mode 100644 raster3d/r3.in.ascii/r3.in.ascii.md create mode 100644 raster3d/r3.in.bin/r3.in.bin.md create mode 100644 raster3d/r3.in.lidar/r3.in.lidar.md create mode 100644 raster3d/r3.in.v5d/r3.in.v5d.md create mode 100644 raster3d/r3.info/r3.info.md create mode 100644 raster3d/r3.mask/r3.mask.md create mode 100644 raster3d/r3.mkdspf/r3.mkdspf.md create mode 100644 raster3d/r3.neighbors/r3.neighbors.md create mode 100644 raster3d/r3.null/r3.null.md create mode 100644 raster3d/r3.out.ascii/r3.out.ascii.md create mode 100644 raster3d/r3.out.bin/r3.out.bin.md create mode 100644 raster3d/r3.out.netcdf/r3.out.netcdf.md create mode 100644 raster3d/r3.out.v5d/r3.out.v5d.md create mode 100644 raster3d/r3.out.vtk/r3.out.vtk.md create mode 100644 raster3d/r3.retile/r3.retile.md create mode 100644 raster3d/r3.showdspf/r3.showdspf.md create mode 100644 raster3d/r3.showdspf/r3.showdspf_opengl_mods.md create mode 100644 raster3d/r3.stats/r3.stats.md create mode 100644 raster3d/r3.support/r3.support.md create mode 100644 raster3d/r3.timestamp/r3.timestamp.md create mode 100644 raster3d/r3.to.rast/r3.to.rast.md create mode 100644 raster3d/raster3dintro.md create mode 100644 scripts/d.background/d.background.md create mode 100644 scripts/d.correlate/d.correlate.md create mode 100644 scripts/d.frame/d.frame.md create mode 100644 scripts/d.out.file/d.out.file.md create mode 100644 scripts/d.polar/d.polar.md create mode 100644 scripts/d.rast.edit/d.rast.edit.md create mode 100644 scripts/d.rast.leg/d.rast.leg.md create mode 100644 scripts/d.shade/d.shade.md create mode 100644 scripts/d.to.rast/d.to.rast.md create mode 100644 scripts/d.what.rast/d.what.rast.md create mode 100644 scripts/d.what.vect/d.what.vect.md create mode 100644 scripts/db.dropcolumn/db.dropcolumn.md create mode 100644 scripts/db.droptable/db.droptable.md create mode 100644 scripts/db.in.ogr/db.in.ogr.md create mode 100644 scripts/db.out.ogr/db.out.ogr.md create mode 100644 scripts/db.test/db.test.md create mode 100644 scripts/db.univar/db.univar.md create mode 100644 scripts/g.download.location/g.download.location.md create mode 100644 scripts/g.download.project/g.download.project.md create mode 100644 scripts/g.extension.all/g.extension.all.md create mode 100644 scripts/g.extension/g.extension.md create mode 100644 scripts/g.extension/testsuite/data/sample_modules/r.plus.example/r.plus.example.md create mode 100644 scripts/g.manual/g.manual.md create mode 100644 scripts/g.search.modules/g.search.modules.md create mode 100644 scripts/i.band.library/i.band.library.md create mode 100644 scripts/i.colors.enhance/i.colors.enhance.md create mode 100644 scripts/i.image.mosaic/i.image.mosaic.md create mode 100644 scripts/i.in.spotvgt/i.in.spotvgt.md create mode 100644 scripts/i.oif/i.oif.md create mode 100644 scripts/i.pansharpen/i.pansharpen.md create mode 100644 scripts/i.spectral/i.spectral.md create mode 100644 scripts/i.tasscap/i.tasscap.md create mode 100644 scripts/m.proj/m.proj.md create mode 100644 scripts/r.blend/r.blend.md create mode 100644 scripts/r.buffer.lowmem/r.buffer.lowmem.md create mode 100644 scripts/r.colors.stddev/r.colors.stddev.md create mode 100644 scripts/r.drain/r.drain.md create mode 100644 scripts/r.fillnulls/r.fillnulls.md create mode 100644 scripts/r.grow/r.grow.md create mode 100644 scripts/r.import/r.import.md create mode 100644 scripts/r.in.aster/r.in.aster.md create mode 100644 scripts/r.in.srtm/r.in.srtm.md create mode 100644 scripts/r.in.wms/r.in.wms.md create mode 100644 scripts/r.mapcalc.simple/r.mapcalc.simple.md create mode 100644 scripts/r.mask/r.mask.md create mode 100644 scripts/r.out.xyz/r.out.xyz.md create mode 100644 scripts/r.pack/r.pack.md create mode 100644 scripts/r.plane/r.plane.md create mode 100644 scripts/r.reclass.area/r.reclass.area.md create mode 100644 scripts/r.rgb/r.rgb.md create mode 100644 scripts/r.semantic.label/r.semantic.label.md create mode 100644 scripts/r.shade/r.shade.md create mode 100644 scripts/r.tileset/r.tileset.md create mode 100644 scripts/r.unpack/r.unpack.md create mode 100644 scripts/r3.in.xyz/r3.in.xyz.md create mode 100644 scripts/v.build.all/v.build.all.md create mode 100644 scripts/v.centroids/v.centroids.md create mode 100644 scripts/v.clip/v.clip.md create mode 100644 scripts/v.db.addcolumn/v.db.addcolumn.md create mode 100644 scripts/v.db.addtable/v.db.addtable.md create mode 100644 scripts/v.db.dropcolumn/v.db.dropcolumn.md create mode 100644 scripts/v.db.droprow/v.db.droprow.md create mode 100644 scripts/v.db.droptable/v.db.droptable.md create mode 100644 scripts/v.db.join/v.db.join.md create mode 100644 scripts/v.db.reconnect.all/v.db.reconnect.all.md create mode 100644 scripts/v.db.renamecolumn/v.db.renamecolumn.md create mode 100644 scripts/v.db.univar/v.db.univar.md create mode 100644 scripts/v.db.update/v.db.update.md create mode 100644 scripts/v.dissolve/v.dissolve.md create mode 100644 scripts/v.import/v.import.md create mode 100644 scripts/v.in.e00/v.in.e00.md create mode 100644 scripts/v.in.geonames/v.in.geonames.md create mode 100644 scripts/v.in.lines/v.in.lines.md create mode 100644 scripts/v.in.mapgen/v.in.mapgen.md create mode 100644 scripts/v.in.wfs/v.in.wfs.md create mode 100644 scripts/v.pack/v.pack.md create mode 100644 scripts/v.rast.stats/v.rast.stats.md create mode 100644 scripts/v.report/v.report.md create mode 100644 scripts/v.to.lines/v.to.lines.md create mode 100644 scripts/v.unpack/v.unpack.md create mode 100644 scripts/v.what.strds/v.what.strds.md create mode 100644 scripts/v.what.vect/v.what.vect.md create mode 100644 scripts/wxpyimgview/wxpyimgview.md create mode 100644 temporal/t.connect/t.connect.md create mode 100644 temporal/t.copy/t.copy.md create mode 100644 temporal/t.create/t.create.md create mode 100644 temporal/t.info/t.info.md create mode 100644 temporal/t.list/t.list.md create mode 100644 temporal/t.merge/t.merge.md create mode 100644 temporal/t.rast.accdetect/t.rast.accdetect.md create mode 100644 temporal/t.rast.accumulate/t.rast.accumulate.md create mode 100644 temporal/t.rast.aggregate.ds/t.rast.aggregate.ds.md create mode 100644 temporal/t.rast.aggregate/t.rast.aggregate.md create mode 100644 temporal/t.rast.algebra/t.rast.algebra.md create mode 100644 temporal/t.rast.colors/t.rast.colors.md create mode 100644 temporal/t.rast.contour/t.rast.contour.md create mode 100644 temporal/t.rast.export/t.rast.export.md create mode 100644 temporal/t.rast.extract/t.rast.extract.md create mode 100644 temporal/t.rast.gapfill/t.rast.gapfill.md create mode 100644 temporal/t.rast.import/t.rast.import.md create mode 100644 temporal/t.rast.list/t.rast.list.md create mode 100644 temporal/t.rast.mapcalc/t.rast.mapcalc.md create mode 100644 temporal/t.rast.neighbors/t.rast.neighbors.md create mode 100644 temporal/t.rast.out.vtk/t.rast.out.vtk.md create mode 100644 temporal/t.rast.series/t.rast.series.md create mode 100644 temporal/t.rast.to.rast3/t.rast.to.rast3.md create mode 100644 temporal/t.rast.to.vect/t.rast.to.vect.md create mode 100644 temporal/t.rast.univar/t.rast.univar.md create mode 100644 temporal/t.rast.what/t.rast.what.md create mode 100644 temporal/t.rast3d.algebra/t.rast3d.algebra.md create mode 100644 temporal/t.rast3d.extract/t.rast3d.extract.md create mode 100644 temporal/t.rast3d.list/t.rast3d.list.md create mode 100644 temporal/t.rast3d.mapcalc/t.rast3d.mapcalc.md create mode 100644 temporal/t.rast3d.univar/t.rast3d.univar.md create mode 100644 temporal/t.register/t.register.md create mode 100644 temporal/t.remove/t.remove.md create mode 100644 temporal/t.rename/t.rename.md create mode 100644 temporal/t.sample/t.sample.md create mode 100644 temporal/t.select/t.select.md create mode 100644 temporal/t.shift/t.shift.md create mode 100644 temporal/t.snap/t.snap.md create mode 100644 temporal/t.support/t.support.md create mode 100644 temporal/t.topology/t.topology.md create mode 100644 temporal/t.unregister/t.unregister.md create mode 100644 temporal/t.upgrade/t.upgrade.md create mode 100644 temporal/t.vect.algebra/t.vect.algebra.md create mode 100644 temporal/t.vect.db.select/t.vect.db.select.md create mode 100644 temporal/t.vect.export/t.vect.export.md create mode 100644 temporal/t.vect.extract/t.vect.extract.md create mode 100644 temporal/t.vect.import/t.vect.import.md create mode 100644 temporal/t.vect.list/t.vect.list.md create mode 100644 temporal/t.vect.observe.strds/t.vect.observe.strds.md create mode 100644 temporal/t.vect.univar/t.vect.univar.md create mode 100644 temporal/t.vect.what.strds/t.vect.what.strds.md create mode 100644 temporal/temporalintro.md create mode 100644 vector/v.buffer/v.buffer.md create mode 100644 vector/v.build.polylines/v.build.polylines.md create mode 100644 vector/v.build/v.build.md create mode 100644 vector/v.category/v.category.md create mode 100644 vector/v.class/v.class.md create mode 100644 vector/v.clean/test/description.md create mode 100644 vector/v.clean/v.clean.md create mode 100644 vector/v.cluster/v.cluster.md create mode 100644 vector/v.colors.out/v.colors.out.md create mode 100644 vector/v.colors/v.colors.md create mode 100644 vector/v.db.connect/v.db.connect.md create mode 100644 vector/v.db.select/v.db.select.md create mode 100644 vector/v.decimate/v.decimate.md create mode 100644 vector/v.delaunay/v.delaunay.md create mode 100644 vector/v.distance/v.distance.md create mode 100644 vector/v.drape/v.drape.md create mode 100644 vector/v.edit/v.edit.md create mode 100644 vector/v.external.out/v.external.out.md create mode 100644 vector/v.external/v.external.md create mode 100644 vector/v.extract/v.extract.md create mode 100644 vector/v.extrude/v.extrude.md create mode 100644 vector/v.fill.holes/v.fill.holes.md create mode 100644 vector/v.generalize/v.generalize.md create mode 100644 vector/v.hull/v.hull.md create mode 100644 vector/v.in.ascii/v.in.ascii.md create mode 100644 vector/v.in.db/v.in.db.md create mode 100644 vector/v.in.dxf/v.in.dxf.md create mode 100644 vector/v.in.lidar/v.in.lidar.md create mode 100644 vector/v.in.ogr/v.in.ogr.md create mode 100644 vector/v.in.pdal/v.in.pdal.md create mode 100644 vector/v.in.region/v.in.region.md create mode 100644 vector/v.info/v.info.md create mode 100644 vector/v.kcv/v.kcv.md create mode 100644 vector/v.kernel/v.kernel.md create mode 100644 vector/v.label.sa/v.label.sa.md create mode 100644 vector/v.label/v.label.md create mode 100644 vector/v.lidar.correction/v.lidar.correction.md create mode 100644 vector/v.lidar.edgedetection/v.lidar.edgedetection.md create mode 100644 vector/v.lidar.growing/v.lidar.growing.md create mode 100644 vector/v.lrs/lrs.md create mode 100644 vector/v.lrs/v.lrs.create/v.lrs.create.md create mode 100644 vector/v.lrs/v.lrs.label/v.lrs.label.md create mode 100644 vector/v.lrs/v.lrs.segment/v.lrs.segment.md create mode 100644 vector/v.lrs/v.lrs.where/v.lrs.where.md create mode 100644 vector/v.mkgrid/v.mkgrid.md create mode 100644 vector/v.neighbors/v.neighbors.md create mode 100644 vector/v.net.alloc/v.net.alloc.md create mode 100644 vector/v.net.allpairs/v.net.allpairs.md create mode 100644 vector/v.net.bridge/v.net.bridge.md create mode 100644 vector/v.net.centrality/v.net.centrality.md create mode 100644 vector/v.net.components/v.net.components.md create mode 100644 vector/v.net.connectivity/v.net.connectivity.md create mode 100644 vector/v.net.distance/v.net.distance.md create mode 100644 vector/v.net.flow/v.net.flow.md create mode 100644 vector/v.net.iso/v.net.iso.md create mode 100644 vector/v.net.path/v.net.path.md create mode 100644 vector/v.net.salesman/v.net.salesman.md create mode 100644 vector/v.net.spanningtree/v.net.spanningtree.md create mode 100644 vector/v.net.steiner/v.net.steiner.md create mode 100644 vector/v.net.timetable/v.net.timetable.md create mode 100644 vector/v.net.visibility/v.net.visibility.md create mode 100644 vector/v.net/v.net.md create mode 100644 vector/v.normal/v.normal.md create mode 100644 vector/v.out.ascii/v.out.ascii.md create mode 100644 vector/v.out.dxf/v.out.dxf.md create mode 100644 vector/v.out.lidar/v.out.lidar.md create mode 100644 vector/v.out.ogr/v.out.ogr.md create mode 100644 vector/v.out.postgis/v.out.postgis.md create mode 100644 vector/v.out.pov/v.out.pov.md create mode 100644 vector/v.out.svg/v.out.svg.md create mode 100644 vector/v.out.vtk/v.out.vtk.md create mode 100644 vector/v.outlier/v.outlier.md create mode 100644 vector/v.overlay/v.overlay.md create mode 100644 vector/v.parallel/v.parallel.md create mode 100644 vector/v.patch/v.patch.md create mode 100644 vector/v.perturb/v.perturb.md create mode 100644 vector/v.profile/v.profile.md create mode 100644 vector/v.proj/v.proj.md create mode 100644 vector/v.qcount/v.qcount.md create mode 100644 vector/v.random/v.random.md create mode 100644 vector/v.reclass/v.reclass.md create mode 100644 vector/v.rectify/v.rectify.md create mode 100644 vector/v.sample/v.sample.md create mode 100644 vector/v.segment/v.segment.md create mode 100644 vector/v.select/v.select.md create mode 100644 vector/v.split/v.split.md create mode 100644 vector/v.support/v.support.md create mode 100644 vector/v.surf.bspline/v.surf.bspline.md create mode 100644 vector/v.surf.idw/v.surf.idw.md create mode 100644 vector/v.surf.rst/v.surf.rst.md create mode 100644 vector/v.timestamp/v.timestamp.md create mode 100644 vector/v.to.3d/v.to.3d.md create mode 100644 vector/v.to.db/v.to.db.md create mode 100644 vector/v.to.points/v.to.points.md create mode 100644 vector/v.to.rast/v.to.rast.md create mode 100644 vector/v.to.rast3/v.to.rast3.md create mode 100644 vector/v.transform/v.transform.md create mode 100644 vector/v.type/v.type.md create mode 100644 vector/v.univar/v.univar.md create mode 100644 vector/v.vect.stats/v.vect.stats.md create mode 100644 vector/v.vol.rst/v.vol.rst.md create mode 100644 vector/v.voronoi/v.voronoi.md create mode 100644 vector/v.what.rast/v.what.rast.md create mode 100644 vector/v.what.rast3/v.what.rast3.md create mode 100644 vector/v.what/v.what.md create mode 100644 vector/vectorintro.md create mode 100644 visualization/ximgview/ximgview.md diff --git a/db/databaseintro.md b/db/databaseintro.md new file mode 100644 index 00000000000..cd76a494483 --- /dev/null +++ b/db/databaseintro.md @@ -0,0 +1,107 @@ +### Attribute management in general + +GRASS can be linked to one or many database management systems (DBMS). +The *db.\** set of commands provides basic SQL support for attribute +management, while the *v.db.\** set of commands operates on the vector +map (see [Vector introduction](vectorintro.md)). + +### Available drivers + +Available drivers are listed in [SQL support in GRASS GIS](sql.md). + +**Notes**: +The DBF driver provides only very limited SQL support (as DBF is not an +SQL DB) while the other DBMS backends (such as SQLite, PostgreSQL, MySQL +etc) provide full SQL support since the SQL commands are sent directly +to the DBMS. For this reason, the SQLite driver is the default DBMI +backend. + +### DB connection management + +The current database management settings are shown or modified with +[db.connect](db.connect.md) for current mapset. Available DBMI drivers +are listed with [db.drivers](db.drivers.md). Some DBMI backends require +a user/password for driver/database to be set with +[db.login](db.login.md). In order to test a driver, run +[db.test](db.test.md). + +### Attribute data import and export + +Attribute data can be imported with [db.in.ogr](db.in.ogr.md) from +various formats and exported with [db.out.ogr](db.out.ogr.md). To +internally copy a a full table or selectively parts of it, use +[db.copy](db.copy.md). + +Further conversion tools: + +- [MDB Tools](https://github.com/mdbtools/mdbtools): Convert MS-Access + data to SQL, DBF, etc. +- [Using OpenOffice.org with SQL + Databases](https://grasswiki.osgeo.org/wiki/Openoffice.org_with_SQL_Databases) + +### SQL commands + +GRASS supports two main SQL operations, execution of an SQL statement +([db.execute](db.execute.md)) and selection of data from a table +([db.select](db.select.md)). See the [SQL help page](sql.md) for +examples. + +### Managing the default DBMI settings + +Per default vector map attributes are stored in SQLite tables. This +default definition can be modified with [db.connect](db.connect.md). If +an external DBMS is used, [db.login](db.login.md) may be required. + +### Creating a database + +Specific commands are explained on the individual driver pages (these +pages are only available if driver was compiled in this installation): + +- DBF: see [DBF](grass-dbf.md) page +- SQLite: [SQLite](grass-sqlite.md) page +- mySQL: [mySQL](grass-mysql.md) and [meSQL](grass-mesql.md) pages +- ODBC: [ODBC](grass-odbc.md) page (connect to Oracle, etc.) +- PostgreSQL: [PostgreSQL](grass-pg.md) and PostGIS page + +### Metadata + +All columns for a given table are listed with +[db.columns](db.columns.md). The command [db.describe](db.describe.md) +describes a table in detail. To list all available tables for a given +database, run [db.tables](db.tables.md). + +### Table maintenance + +To drop a column from a selected attribute table, use +[db.dropcolumn](db.dropcolumn.md). With [db.droptable](db.droptable.md) +an attribute table can be deleted. + +### Database Schema + +Currently schema support only works for PostgreSQL connections. Default +schema can be set with [db.connect](db.connect.md). Note that the +default schema will be used by all db.\* modules. + +[db.tables](db.tables.md) returns 'schema.table' if schemas are +available in the database. + +### Migrating to a different database engine + +To migrate a GRASS database table (or a GRASS vector map) to a different +DBMI engine, the best solution is to create a new MAPSET, define the +DBMI settings accordingly with [db.connect](db.connect.md) and if +needed, [db.login](db.login.md). Then the table of interest can be +copied over with [db.copy](db.copy.md) from the original MAPSET. +Likewise, a vector map including its table(s) are copied from the +original MAPSET to the current MAPSET with [g.copy](g.copy.md). + +### See also + +- [Introduction into raster data processing](rasterintro.md) +- [Introduction into 3D raster data (voxel) + processing](raster3dintro.md) +- [Introduction into vector data processing](vectorintro.md) +- [Introduction into image processing](imageryintro.md) +- [Introduction into temporal data processing](temporalintro.md) +- [Projections and spatial transformations](projectionintro.md) +- [Graphical User Interface](wxguiintro.md) diff --git a/db/db.columns/db.columns.md b/db/db.columns/db.columns.md new file mode 100644 index 00000000000..f025221664e --- /dev/null +++ b/db/db.columns/db.columns.md @@ -0,0 +1,52 @@ +## DESCRIPTION + +*db.columns* lists all columns for a give table. Connection to databases +are supported through dbf, shp, odbc and pg drivers. + +## NOTE + +If parameters for database connection are already set with +[db.connect](db.connect.md), they are taken as default values and do not +need to be spcified each time. + +## EXAMPLES + +### List columns of a PostgreSQL attribute table + +```bash +db.columns table=zipcodes_wake driver=pg database=grassdb +``` + +*If the database parameters are already set, the columns can be listed +directly* + +```bash +db.columns table=zipcodes_wake +``` + +### List columns from Shape file with DBF attribute table + +```bash +db.columns table=zipcodes_wake driver=dbf database=/grassdata/nc_spm_08/PERMANENT/dbf/ +``` + +### List columns of table in SQLite database + +Note that the SQLite backend is the default setting. + +```bash +db.columns driver=sqlite table=archsites database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db' +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.describe](db.describe.md), +[db.drivers](db.drivers.md), [db.droptable](db.droptable.md), +[db.execute](db.execute.md), [db.login](db.login.md), +[db.tables](db.tables.md), [GRASS SQL interface](sql.md)* + +[GRASS SQL interface](sql.md) + +## AUTHOR + +Radim Blazek, ITC-Irst, Trento, Italy diff --git a/db/db.connect/db.connect.md b/db/db.connect/db.connect.md new file mode 100644 index 00000000000..97e99713850 --- /dev/null +++ b/db/db.connect/db.connect.md @@ -0,0 +1,136 @@ +## DESCRIPTION + +*db.connect* allows the user to set database connection parameters. +These parameters are then taken as default values by modules so that the +user does not need to enter the parameters each time. + +The default database backend in GRASS GIS is [SQLite](grass-sqlite.md) +(since version 7). + +## NOTES + +Values are stored in the mapset's `VAR` file; the connection is not +tested for validity. + +The **-p** flag will display the current connection parameters. + +The **-c** flag will silently check if the connection parameters have +been set, and if not will set them to use GRASS's default values. +(useful in scripts before you attempt to create a new database table) + +To connect a vector map to a database table, use +*[v.db.connect](v.db.connect.md)* or +*[v.db.addtable](v.db.addtable.md)*. + +## EXAMPLES + +### SQLite (default backend) + +Local storage: + +```bash +db.connect -d +db.connect -p +db.tables -p +``` + +The SQLite database file is created automatically when used the first +time. + +See [SQLite](grass-sqlite.md) database driver for details. + +### PostgreSQL (local connection) + +Local storage, database tables stored in database "mydb" (may require +the use of *[db.login](db.login.md)*): + +```bash +db.connect driver=pg database=mydb +db.login user=myname pass=secret +db.connect -p +db.tables -p +``` + +See [PostgreSQL](grass-pg.md) database driver for details. + +### PostgreSQL (network connection) + +Network storage, database tables stored in database "mydb" (may require +the use of *[db.login](db.login.md)*): + +```bash +db.connect driver=pg database=mydb +db.login user=myname pass=secret host=myserver.com port=6666 +db.connect -p +db.tables -p +``` + +See [PostgreSQL](grass-pg.md) database driver for details. + +### MySQL (local connection) + +Local storage, database tables stored in database "mydb" (may require +the use of *[db.login](db.login.md)*): + +```bash +db.connect driver=mysql database=mydb +db.login user=myname pass=secret +db.connect -p +db.tables -p +``` + +See [MySQL](grass-mysql.md) database driver for details. + +### MySQL (network connection) + +Network storage, database tables stored in database "mydb" (may require +the use of *[db.login](db.login.md)*): + +```bash +db.connect driver=mysql database=mydb +db.login user=myname pass=secret host=myserver.com +db.connect -p +db.tables -p +``` + +See [MySQL](grass-mysql.md) database driver for details. + +### ODBC + +Network storage, database tables stored in database "mydb" (may require +the use of *[db.login](db.login.md)*): + +```bash +db.connect driver=odbc database=mydb +db.login user=myname pass=secret +db.connect -p +db.tables -p +``` + +See [ODBC](grass-odbc.md) database driver for details. + +### DBF (local, not recommended) + +Local storage (the dbf/ subdirectory in the mapset must exist or must be +created by the user): + +```bash +db.connect driver=dbf database='$GISDBASE/$LOCATION_NAME/$MAPSET/dbf/' +db.tables -p +``` + +See [DBF](grass-dbf.md) database driver for details. + +## SEE ALSO + +*[db.columns](db.columns.md), [db.copy](db.copy.md), +[db.drivers](db.drivers.md), [db.login](db.login.md), +[db.tables](db.tables.md), [v.db.addtable](v.db.addtable.md), +[v.db.connect](v.db.connect.md)* + +[GRASS SQL interface](sql.md) + +## AUTHORS + +Main author: Radim Blazek, ITC-Irst, Trento, Italy +GRASS 7 improvements: Martin Landa, Markus Metz diff --git a/db/db.copy/db.copy.md b/db/db.copy/db.copy.md new file mode 100644 index 00000000000..7c984690053 --- /dev/null +++ b/db/db.copy/db.copy.md @@ -0,0 +1,72 @@ +## DESCRIPTION + +*db.copy* allows the user to copy a table between two databases. +Databases can be connected through different drivers (see examples +below). + +## NOTES + +Attribute tables can be copied using *db.copy* and, when to be +associated to a vector map, assigned to the map with +*[v.db.connect](v.db.connect.md)*. Current connection settings are saved +in the file *\$LOCATION/vector_map/dbln*. + +## EXAMPLES + +### From DBF to PostgreSQL + +*Storing table 'geonames.dbf' (in current directory) into PostgreSQL +through ODBC:* + +```bash +db.copy from_driver=dbf from_database='$GISDBASE/$LOCATION_NAME/PERMANENT/dbf' \ + from_table=geonames to_driver=pg to_database="host=pgserver,dbname=testdb" \ + to_table=geonames +``` + +### From PostgreSQL to DBF + +```bash +db.copy from_driver=pg from_database="host=pgserver.example.org,dbname=testdb" \ + from_table=origtable to_driver=dbf \ + to_database='$GISDBASE/$LOCATION_NAME/$MAPSET/dbf' to_table=origtable +``` + +### From PostgreSQL to PostgreSQL with condition + +```bash +db.copy from_driver=pg from_database="host=localhost,dbname=testdb" \ + from_table=geonames to_driver=pg to_database="host=localhost,dbname=testdb" \ + to_table=selection where="cat < 500" +``` + +### From DBF to SQLite + +```bash +db.copy from_driver=dbf from_database='$GISDBASE/$LOCATION_NAME/PERMANENT/dbf' \ + from_table=geonames_features to_driver=sqlite \ + to_database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db' to_table=geonames_features + +# convenient viewer: +sqlitebrowser $HOME/grassdata/nc_spm_08/user1/sqlite/sqlite.db +``` + +### From SQLite to DBF + +```bash +db.copy from_driver=sqlite from_database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db' \ + from_table=ammprv to_driver=dbf to_database='$GISDBASE/$LOCATION_NAME/$MAPSET/dbf/' \ + to_table=ammprv +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.drivers](db.drivers.md), +[db.login](db.login.md), [v.db.connect](v.db.connect.md), +[v.clean](v.clean.md)* + +[GRASS SQL interface](sql.md) + +## AUTHOR + +Radim Blazek, ITC-irst, Trento, Italy diff --git a/db/db.createdb/db.createdb.md b/db/db.createdb/db.createdb.md new file mode 100644 index 00000000000..bfd3dc9edb3 --- /dev/null +++ b/db/db.createdb/db.createdb.md @@ -0,0 +1,56 @@ +## DESCRIPTION + +*db.createdb* allows the user to create a new empty database through +different drivers. A working database connection needs to be +established, see *[db.login](db.login.md)*. + +Currently only [SQLite](grass-sqlite.md) and [PostgreSQL](grass-pg.md) +database drivers are supported. + +## EXAMPLES + +### Create a new SQLite file-based database + +Note that the standard GRASS GIS SQLite database is by default generated +in the user's current mapset. This example shows an out-of-mapset +database file creation: + +```bash +db.createdb driver=sqlite database=/opt/sqlite.db +``` + +### Create a new PostgreSQL database + +Create a new PostgreSQL database (after the PostgreSQL connection got +established through the *pg* driver): + +```bash +db.createdb driver=pg database=grassdb +``` + +Create a new PostgreSQL database (after the PostgreSQL connection got +established through the *odbc* driver): + +```bash +db.createdb driver=odbc database=grassdb +``` + +## TODO + +Support other database drivers, too. + +## SEE ALSO + +*[db.columns](db.columns.md), [db.connect](db.connect.md), +[db.describe](db.describe.md), [db.drivers](db.drivers.md), +[db.dropdb](db.dropdb.md), [db.droptable](db.droptable.md), +[db.execute](db.execute.md), [db.login](db.login.md), +[db.tables](db.tables.md)* + +[GRASS SQL interface](sql.md) + +## AUTHORS + +Radim Blazek, ITC-Irst, Trento, Italy +SQLite and PostgreSQL support by Martin Landa, Czech Technical +University in Prague, Czech Republic diff --git a/db/db.databases/db.databases.md b/db/db.databases/db.databases.md new file mode 100644 index 00000000000..b9dcbb086b6 --- /dev/null +++ b/db/db.databases/db.databases.md @@ -0,0 +1,46 @@ +## DESCRIPTION + +*db.databases* lists all databases for a given **driver** and optionally +**location**. + +## NOTES + +Currently supported database drivers are *[SQLite](grass-sqlite.md)*, +*[PostgreSQL](grass-pg.md)*, and *[ODBC](grass-odbc.md)*. + +Default **location** for SQLite driver is the full path for the current +mapset. For PostgreSQL driver it's empty connection string. + +## EXAMPLES + +List SQLite databases in the current mapset: + +```bash +db.databases driver=sqlite +``` + +List SQLite databases in a given directory: + +```bash +db.databases driver=sqlite location=/opt/sqlite +``` + +List PostgreSQL databases from database server running on given port: + +```bash +db.databases driver=pg location="host=server_name port=5333" +``` + +## SEE ALSO + +*[db.columns](db.columns.md), [db.describe](db.describe.md), +[db.drivers](db.drivers.md), [db.execute](db.execute.md), +[db.login](db.login.md), [db.tables](db.tables.md)* + +[GRASS SQL interface](sql.md) + +## AUTHORS + +Radim Blazek, ITC-Irst, Trento, Italy +Updated for GRASS 7 by Martin Landa, Czech Technical University in +Prague, Czech Republic diff --git a/db/db.describe/db.describe.md b/db/db.describe/db.describe.md new file mode 100644 index 00000000000..835886e9e32 --- /dev/null +++ b/db/db.describe/db.describe.md @@ -0,0 +1,300 @@ +## DESCRIPTION + +*db.describe* displays table information. If parameter **-c** is used +only column names instead of full column descriptions is given. + +## NOTE + +If parameters for database connection are already set with +[db.connect](db.connect.md), they are taken as default values and do not +need to be spcified each time. + +## EXAMPLES + +*List column descriptions of table in SQLite database (note that this is +the default setting)* + +```bash +db.describe driver=sqlite table=hospitals \ + database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db' + +# or simply +db.describe myarchsites +``` + +### DBF example + +```bash +db.describe -c table=hospitals database='$GISDBASE/$LOCATION_NAME/PERMANENT/dbf/' \ + driver=dbf +ncols: 16 +nrows: 160 +Column 1: cat:INTEGER:11 +Column 2: OBJECTID:INTEGER:11 +Column 3: AREA:DOUBLE PRECISION:20 +[...] +``` + +```bash +db.describe table=hospitals database='$GISDBASE/$LOCATION_NAME/PERMANENT/dbf/' \ + driver=dbf +table:hospitals +description: +insert:yes +delete:yes +ncols:16 +nrows:160 + +column:cat +description: +type:INTEGER +len:11 +scale:0 +precision:10 +default: +nullok:yes +select:yes +update:yes + +column:OBJECTID +description: +type:INTEGER +[...] +``` + +### JSON Output + +```bash +db.describe table=hospitals format=json +``` + +```bash +{ + "table": "hospitals", + "description": "", + "insert": null, + "delete": null, + "ncols": 16, + "nrows": 160, + "columns": [ + { + "position": 1, + "column": "cat", + "description": "", + "type": "INTEGER", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 2, + "column": "OBJECTID", + "description": "", + "type": "INTEGER", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 3, + "column": "AREA", + "description": "", + "type": "DOUBLE PRECISION", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 4, + "column": "PERIMETER", + "description": "", + "type": "DOUBLE PRECISION", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 5, + "column": "HLS_", + "description": "", + "type": "INTEGER", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 6, + "column": "HLS_ID", + "description": "", + "type": "INTEGER", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 7, + "column": "NAME", + "description": "", + "type": "CHARACTER", + "length": 45, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 8, + "column": "ADDRESS", + "description": "", + "type": "CHARACTER", + "length": 35, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 9, + "column": "CITY", + "description": "", + "type": "CHARACTER", + "length": 16, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 10, + "column": "ZIP", + "description": "", + "type": "CHARACTER", + "length": 5, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 11, + "column": "COUNTY", + "description": "", + "type": "CHARACTER", + "length": 12, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 12, + "column": "PHONE", + "description": "", + "type": "CHARACTER", + "length": 14, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 13, + "column": "CANCER", + "description": "", + "type": "CHARACTER", + "length": 4, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 14, + "column": "POLYGONID", + "description": "", + "type": "INTEGER", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 15, + "column": "SCALE", + "description": "", + "type": "DOUBLE PRECISION", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + }, + { + "position": 16, + "column": "ANGLE", + "description": "", + "type": "DOUBLE PRECISION", + "length": 20, + "scale": 0, + "precision": 0, + "default": null, + "nullok": true, + "select": null, + "update": null + } + ] +} +``` + +## SEE ALSO + +*[db.columns](db.columns.md), [db.droptable](db.droptable.md), +[db.execute](db.execute.md), [db.login](db.login.md), +[db.tables](db.tables.md), [GRASS SQL interface](sql.md)* + +## AUTHOR + +Radim Blazek, ITC-Irst, Trento, Italy diff --git a/db/db.drivers/db.drivers.md b/db/db.drivers/db.drivers.md new file mode 100644 index 00000000000..4f366e59b1b --- /dev/null +++ b/db/db.drivers/db.drivers.md @@ -0,0 +1,26 @@ +## DESCRIPTION + +*db.drivers* lists all database drivers (DBMI backends). + +## EXAMPLE + +Show all installed GRASS database drivers: + +```bash +db.drivers -p +pg +ogr +sqlite +dbf +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.describe](db.describe.md), +[db.droptable](db.droptable.md), [db.execute](db.execute.md), +[db.login](db.login.md), [db.tables](db.tables.md), [GRASS SQL +interface](sql.md)* + +## AUTHOR + +Radim Blazek, ITC-Irst, Trento, Italy diff --git a/db/db.dropdb/db.dropdb.md b/db/db.dropdb/db.dropdb.md new file mode 100644 index 00000000000..b24feab1b4b --- /dev/null +++ b/db/db.dropdb/db.dropdb.md @@ -0,0 +1,41 @@ +## DESCRIPTION + +*db.dropdb* removes an existing database using given database +**driver**. Currently only [SQLite](grass-sqlite.md) and +[PostgreSQL](grass-pg.md) database drivers are supported. + +## EXAMPLES + +### Drop (delete) an existing database connected through SQLite driver + +Note that the standard GRASS GIS SQLite database is by default found in +the user's current mapset. This example shows an out-of-mapset database +removal: + +```bash +db.dropdb driver=sqlite database=/opt/sqlite.db +``` + +### Drop an existing database connected through PostgreSQL driver + +```bash +db.dropdb driver=pg database=grassdb +``` + +## TODO + +Support other database drivers, too. + +## SEE ALSO + +*[db.createdb](db.createdb.md), [db.describe](db.describe.md), +[db.droptable](db.droptable.md), [db.execute](db.execute.md), +[db.login](db.login.md), [db.tables](db.tables.md)* + +[GRASS SQL interface](sql.md) + +## AUTHORS + +Radim Blazek, ITC-Irst, Trento, Italy +SQLite and PostgreSQL support by Martin Landa, Czech Technical +University in Prague, Czech Republic diff --git a/db/db.execute/db.execute.md b/db/db.execute/db.execute.md new file mode 100644 index 00000000000..390aa416ca7 --- /dev/null +++ b/db/db.execute/db.execute.md @@ -0,0 +1,116 @@ +## DESCRIPTION + +*db.execute* allows the user to execute SQL statements. + +## NOTES + +*db.execute* only executes SQL statements and does not return any data. +If you need data returned from the database, use +*[db.select](db.select.md)*. + +If parameters for database connection are already set with +*[db.connect](db.connect.md)*, they are taken as default values and do +not need to be specified each time. + +If you have a large number of SQL commands to process, it is much faster +to place all the SQL statements into a text file and use **input** file +parameter than it is to process each statement individually in a loop. +If multiple instruction lines are given, each SQL line must end with a +semicolon. + +Please see the individual *[GRASS SQL interface](sql.md)* for how to +create a new database. + +## EXAMPLES + +Create a new table with columns 'cat' and 'soiltype': + +```bash +db.execute sql="CREATE TABLE soils (cat integer, soiltype varchar(10))" +``` + +Create a new table using a file with SQL statements + +```bash +db.execute driver=odbc database=grassdb input=file.sql +``` + +Insert new row into attribute table: + +```bash +db.execute sql="INSERT INTO mysites (id,name,east,north) values (30,'Ala',1657340,5072301)" +``` + +Update attribute entries to new value based on SQL rule: + +```bash +db.execute sql="UPDATE roads SET travelcost=5 WHERE cat=1" +``` + +Update attribute entries to new value based on SQL rule: + +```bash +db.execute sql="UPDATE dourokukan SET testc=50 WHERE testc is NULL" +``` + +Delete selected rows from attribute table: + +```bash +db.execute sql="DELETE FROM gsod_stationlist WHERE latitude < -91" +``` + +Add new column to attribute table: + +```bash +db.execute sql="ALTER TABLE roads ADD COLUMN length double" +``` + +Column type conversion - update new column from existing column (all +drivers except for DBF): + +```bash +# 'z_value' is varchar and 'z' is double precision: +echo "UPDATE geodetic_pts SET z = CAST(z_value AS numeric)" | db.execute input=- +``` + +Drop column from attribute table: + +```bash +db.execute sql="ALTER TABLE roads DROP COLUMN length" +``` + +Drop table (not supported by all drivers): + +```bash +db.execute sql="DROP TABLE fmacopy" +``` + +Update attribute with multiple SQL instructions in file (e.g., +`file.sql`, instruction line must end with a semicolon): + +```bash +UPDATE roads SET travelcost=5 WHERE cat=1; +UPDATE roads SET travelcost=2 WHERE cat=2; + +db.execute input=file.sql +``` + +Join table 'myroads' to table 'extratab' based on common 'cat' column +values (not supported by DBF driver): + +```bash +db.execute sql="UPDATE extratab SET names=(SELECT label FROM myroads WHERE extratab.cat=myroads.cat)" +``` + +## SEE ALSO + +*[db.columns](db.columns.md), [db.describe](db.describe.md), +[db.drivers](db.drivers.md), [db.droptable](db.droptable.md), +[db.login](db.login.md), [db.select](db.select.md), +[db.tables](db.tables.md),* + +*[GRASS SQL interface](sql.md)* + +## AUTHOR + +CERL diff --git a/db/db.login/db.login.md b/db/db.login/db.login.md new file mode 100644 index 00000000000..f242c4b58fe --- /dev/null +++ b/db/db.login/db.login.md @@ -0,0 +1,55 @@ +## DESCRIPTION + +*db.login* sets login parameters such an user name and optionally also a +password, a hostname or a port for the connection to the selected +**database** through the DB **driver**. + +## NOTE + +Options **host** and **port** are related to only SQL database backends +like [PostgreSQL](grass-pg.md), [MySQL](grass-mysql.md) or +[ODBC](grass-odbc.md). + +Note that the passwords are stored in a hidden, *unencrypted* file in +the user account, specifically + +- in the 'home' directory, i.e. `$HOME/.grass8/dblogin` (Unix-like + systems) +- `%APPDATA%\Roaming\GRASS8\dblogin` (MS-Windows) + +Only the file owner can access this file. + +## EXAMPLES + +Only username specified (assuming locally accessible PostgreSQL DB +without password): + +```bash +db.login driver=pg database=mydb +``` + +Username, password and hostname specified (note that the command lines +history will store the password in this way): + +```bash +db.login driver=pg database=mydb user=bacava password=secret host=db.example.com +``` + +Username and empty password specified: + +```bash +db.login driver=pg database=mydb user=bacava password="" +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.test](db.test.md), +[db.tables](db.tables.md)* + +[SQL support in GRASS GIS](sql.md) + +## AUTHOR + +Radim Blazek +Support for hostname and port by Martin Landa, OSGeoREL, Czech Technical +University in Prague, Czech Republic (GRASS 7.1) diff --git a/db/db.select/db.select.md b/db/db.select/db.select.md new file mode 100644 index 00000000000..a8d4f41ce70 --- /dev/null +++ b/db/db.select/db.select.md @@ -0,0 +1,101 @@ +## DESCRIPTION + +*db.select* prints result of selection from database based on SQL +statement read from input file or from standard input to standard +output. Each individual query has to be written on one single line and +different queries have to be written on separate lines. + +## NOTE + +If parameters for database connection are already set with +*[db.connect](db.connect.md)*, they are taken as default values and do +not need to be specified each time. Output will be displayed to standard +output or can be directed to a file (option **output**). + +## EXAMPLES + +### Basic usage + +```bash +db.select sql="select * from roads" +``` + +or + +```bash +echo "select * from roads" | db.select input=- +``` + +or + +```bash +db.select input=file.sql +``` + +or + +```bash +cat file.sql | db.select input=- +``` + +Select all from table roads: + +```bash +db.select -c driver=odbc database=mydb table=hospitals \ + input=file.sql output=result.csv +``` + +Select some string attribute, exclude others: + +```bash +db.select sql="SELECT * FROM archsites WHERE str1 <> 'No Name'" +``` + +Select some string attribute with ZERO length: + +```bash +db.select sql="SELECT * FROM archsites WHERE str1 IS NULL" +``` + +Select coordinates from PostGIS table: + +```bash +db.select sql="SELECT x(geo),y(geo) FROM localizzazione" +``` + +### Execute multiple SQL statements + +```bash +cat file.sql +SELECT * FROM busstopsall WHERE cat = 1 +SELECT cat FROM busstopsall WHERE cat > 4 AND cat < 8 + +db.select input=file.sql +``` + +### Count number of cases falling into same position + +When multiple observation have the spatial coordinates, they can still +be counted (if needed, coordinates can be uploaded to the attribute +table by *v.to.db*: + +```bash +db.select sql="SELECT long,lat,site_id,department,obs,COUNT(long) as count_cases \ + FROM diseases GROUP BY long,lat" +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.describe](db.describe.md), +[db.drivers](db.drivers.md), [db.droptable](db.droptable.md), +[db.execute](db.execute.md), [db.login](db.login.md), +[db.tables](db.tables.md)* + +*[GRASS SQL interface](sql.md)* + +## AUTHORS + +Original author unknown (probably CERL) +Modifications by Radim Blazek, ITC-Irst, Trento, Italy +Support for multiple statements by Martin Landa, Czech Technical +University in Prague diff --git a/db/db.tables/db.tables.md b/db/db.tables/db.tables.md new file mode 100644 index 00000000000..acc26d2bb05 --- /dev/null +++ b/db/db.tables/db.tables.md @@ -0,0 +1,39 @@ +## DESCRIPTION + +*db.tables* lists all tables for a given database. + +## NOTE + +If parameters for database connection are already set with +[db.connect](db.connect.md), they are taken as default values and do not +need to be spcified each time. + +## EXAMPLES + +### List all tables if database connection is already set + +```bash +db.tables -p +``` + +### List all DBF tables + +```bash +db.tables driver=dbf database=/grassdata/nc_spm_08/user1/PERMANENT/dbf +``` + +### List all tables in SQLite database (note that this is the default setting) + +```bash +db.tables -p driver=sqlite database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db' +``` + +## SEE ALSO + +*[db.columns](db.columns.md), [db.droptable](db.droptable.md), +[db.login](db.login.md), [db.execute](db.execute.md), [GRASS SQL +interface](sql.md)* + +## AUTHOR + +Unknown diff --git a/db/drivers/dbf/grass-dbf.md b/db/drivers/dbf/grass-dbf.md new file mode 100644 index 00000000000..d5a346850cb --- /dev/null +++ b/db/drivers/dbf/grass-dbf.md @@ -0,0 +1,116 @@ +The DBF driver is a file based attribute table driver. + +## Defining the DBF driver + +The DBF driver is a file based driver, in theory no user interaction is +required. However, if the settings should be set back from a different +driver to the DBF driver, the following step is required: + +```bash +# keep single quotes: +db.connect driver=dbf database='$GISDBASE/$LOCATION_NAME/$MAPSET/dbf/' +db.connect -p +``` + +The dbf/ subdirectory in the mapset must exist or must be created by the +user. + +## Creating a DBF table + +DBF tables are created by GRASS when generating a vector map with +attributes and having defined the DBF as attribute driver. + +If a DBF table has to be created manually, [db.execute](db.execute.md) +can be used or a spreadsheet application. Also [db.copy](db.copy.md) is +sometimes useful as well as [db.in.ogr](db.in.ogr.md) to import external +tables. + +## Supported SQL commands by DBF driver + +```bash + ALTER TABLE table ADD [COLUMN] columndef + ALTER TABLE table DROP COLUMN colname + CREATE TABLE table ( columndefs ) + DROP TABLE table + SELECT columns FROM table + SELECT columns FROM table WHERE condition + SELECT columns FROM table ORDER BY column + DELETE FROM table + DELETE FROM table WHERE condition + INSERT INTO table VALUES (value1[,value2,...]) + INSERT INTO table ( column1[,column2,...] ) VALUES (value1[,value2,...]) + UPDATE table SET assignment1[,assignment2,...] + UPDATE table SET assignment1[,assignment2,...] WHERE condition +``` + +## Operators available in conditions + +```bash + "=" : equal + "<" : smaller than + "<=" : smaller/equal than + ">" : larger than + ">=" : larger/equal than + "<>" : not equal + "~" : Substring matching (non-standard SQL) + "%" : Substring matching (limited functionality) +``` + +Arithmetic expressions using constants and field values are allowed in +condition clauses and in the RHS of assignments. +Usual precedence rules and bracketing (using '(' and ')') are +supported. +Type conversion is performed if necessary (experimental). + +Conditions allow boolean expressions using the AND, OR and NOT +operators, with the usual precedence rules. + +NULLs can be tested by 'colname IS NULL' in conditions. The negation is +'colname NOT NULL'. + +Sorting: Empty fields in a character column are sorted to the end. + +## LIMITATIONS OF THE DBF DRIVER + +The DBF driver supports only a **few SQL statements** since the DBF +tables are intended for simple table storage. DBF column names are +limited to 10 characters (as defined in the DBF specifications). For +example, + +- aggregate functions (sum, count, min, max,...) are **not** supported + in SELECT clauses; +- mathematic functions (sin, cos, exp, log,...) are **not** supported in + expressions; +- SQL query with IN are **not** supported. + +## ERROR MESSAGES + +An error message such as: + +```bash +DBMI-DBF driver error: +SQL parser error: syntax error, unexpected NAME processing 'IN'.. +``` + +indicates that an unsupported SQL statement (here, 'IN') was used. The +only solution is to switch the DBMI backend to a real SQL engine +(SQLite, PostgreSQL, MySQL etc.). See [SQL support in GRASS +GIS](sql.md). + +An error message such as: + +```bash +DBMI-DBF driver error: +SQL parser error: syntax error, unexpected DESC, expecting NAME processing 'DESC' +``` + +indicates that a column name corresponds to a reserved SQL word (here: +'DESC'). A different column name should be used. If this happens during +import with *v.in.ogr*, the *cnames* parameter can be used to assign +different column names on the fly. + +## SEE ALSO + +*[db.connect](db.connect.md), [SQL support in GRASS GIS](sql.md) +[DBF Specifications](http://shapelib.maptools.org/dbf_api.html) +(Shapelib)* diff --git a/db/drivers/mysql/grass-mesql.md b/db/drivers/mysql/grass-mesql.md new file mode 100644 index 00000000000..f064d4fccb4 --- /dev/null +++ b/db/drivers/mysql/grass-mesql.md @@ -0,0 +1,59 @@ +MySQL database driver enables GRASS to store vector attributes in MySQL +embedded database without necessity to run MySQL server. + +## Driver and database name + +GRASS modules require 2 parameters to connect to a database. Those +parameters are 'driver' and 'database'. For MySQL embedded driver the +parameter 'driver' should be set to value 'mesql'. The parameter +'database' is a full path to the directory where database tables are +stored. The best place is a directory in the mapset. The directory must +be created before use of the driver. In the name of database it is +possible to use 3 variables: + +- $GISDBASE - path to current GISBASE +- $LOCATION_NAME - name of current location +- $MAPSET - name of current mapset + +Examples of connection parameters: + +```bash +db.connect driver=mesql database='$GISDBASE/$LOCATION_NAME/$MAPSET/mysql' +db.connect driver=mesql database=/home/user1/db +``` + +## Data types, indexes + +For more information about supported data types and indexes see the +documentation for [MySQL (mysql) driver](grass-mysql.md). + +## Database type + +Because database closing was found very slow if InnoDB was used, the +InnoDB storage is disabled by default (hardcoded '--skip-innodb' server +option). + +## Note + +The embedded server is started with hardcoded '--bootstrap' option to +avoid warning about missing "mysql.time_zone_leap_second table". This +can be fixed in future. + +## Troubleshooting: SQL syntax error + +Attempting to use a reserved SQL word as column or table name will +result in a "SQL syntax" error. The list of reserved words for MySQL can +be found in the [MySQL +manual](https://dev.mysql.com/doc/refman/8.4/en/keywords.html#keywords-in-current-series). + +## AUTHOR + +Radim Blazek + +Credits: Development of the driver was sponsored by +[Faunalia](https://www.faunalia.it) (Italy) as part of a project for +[ATAC](https://www.atac.roma.it/). + +## SEE ALSO + +*[db.connect](db.connect.md), [SQL support in GRASS GIS](sql.md)* diff --git a/db/drivers/mysql/grass-mysql.md b/db/drivers/mysql/grass-mysql.md new file mode 100644 index 00000000000..f20e648e3ab --- /dev/null +++ b/db/drivers/mysql/grass-mysql.md @@ -0,0 +1,106 @@ +MySQL database driver enables GRASS to store vector attributes in MySQL +server. + +Because vector attribute tables are created automatically when a new +vector is written and the name of the table is the same as the name of +the vector it is good practice to create a new database for each GRASS +mapset. + +## Creating a MySQL database + +A new database is created within MySQL: + +```bash +mysql> CREATE DATABASE mydb; +``` + +See the MySQL manual for details. + +## Driver and database name + +GRASS modules require 2 parameters to connect to a database. Those +parameters are 'driver' and 'database'. For MySQL driver the parameter +'driver' should be set to value 'mysql'. The parameter 'database' can be +given in two formats: + +- Database name - in case of connection from localhost +- String of comma separated list of key=value options. Supported options + are: + - dbname - database name + - host - host name or IP address + - port - server port number + +Examples of connection parameters: + +```bash +db.connect driver=mysql database=mytest +db.connect driver=mysql database='dbname=mytest,host=test.grass.org' +``` + +## Data types + +GRASS supports almost all MySQL data types with following limitations: + +- Binary columns (BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB, BLOB, + LONGBLOB) are not not supported. If a table with binary column(s) is + used in GRASS a warning is printed and only the supported columns are + returned in query results. +- Columns of type SET and ENUM are represented as string (VARCHAR). +- Very large integers in columns of type BIGINT can be lost or corrupted + because GRASS does not support 64 bin integeres on most platforms. +- GRASS does not currently distinguish types TIMESTAMP and DATETIME. + Both types are in GRASS interpreted as TIMESTAMP. + +## Indexes + +GRASS modules automatically create index on key column of vector +attributes table. The index on key column is important for performance +of modules which update the attribute table, for example v.to.db, +v.distance and v.what.rast. + +## Privileges + +Because MySQL does not support groups of users and because only MySQL +'root' can grant privileges to other users GRASS cannot automatically +grant select privileges on created tables to group of users. + +If you want to give privilege to read data from your mapset to other +users you have to ask your MySQL server administrator to grant select +privilege to them on the MySQL database used for that mapset. For +example, to allow everybody to read data in from your database 'mydb': + +```bash +shell> mysql --user=root mysql +mysql> GRANT SELECT ON mydb.* TO ''@'%'; +``` + +## Schemas + +Because MySQL does not support database schemas the parameter 'schema' +of module db.connect should never be set to any value. If you set that +parameter for MySQL driver GRASS will try to write tables to the +specified schema which will result in errors. + +## Groups + +MySQL does not support user groups. Any settings specified by 'group' +parameter of module db.connect are ignored by GRASS for MySQL driver. + +## Troubleshooting: SQL syntax error + +Attempting to use a reserved SQL word as column or table name will +result in a "SQL syntax" error. The list of reserved words for MySQL can +be found in the [MySQL +manual](https://dev.mysql.com/doc/refman/8.4/en/keywords.html#keywords-in-current-series). + +## AUTHOR + +Radim Blazek + +Credits: Development of the driver was sponsored by +[Faunalia](https://www.faunalia.it) (Italy) as part of a project for +[ATAC](https://www.atac.roma.it/). + +## SEE ALSO + +*[db.connect](db.connect.md), [SQL support in GRASS GIS](sql.md)* diff --git a/db/drivers/odbc/grass-odbc.md b/db/drivers/odbc/grass-odbc.md new file mode 100644 index 00000000000..6db7922b110 --- /dev/null +++ b/db/drivers/odbc/grass-odbc.md @@ -0,0 +1,140 @@ +Communication between GRASS and ODBC database for attribute management: + +| | | | | | +|:-------------------:|:-----------------:|:--------------:|:-----------------:|:----------------:| +| GRASS module \<-\>  | \<--\> | ODBC Interface | \<--\> | RDBMS | +| ***GRASS*** | ***DBMI driver*** | ***unixODBC*** | ***ODBC driver*** | ***PostgreSQL*** | +| | | | | ***Oracle*** | +| | | | | ***...*** | + +## Supported SQL commands + +All SQL commands supported by ODBC. + +## Operators available in conditions + +All SQL operators supported by ODBC. + +## EXAMPLE + +In this example we copy the dbf file of a SHAPE map into ODBC, then +connect GRASS to the ODBC DBMS. Usually the table will be already +present in the DBMS. + +### Defining the ODBC connection + +#### MS-Windows + +On MS-Windows, in order to be able to connect, the ODBC connection needs +to be configured using dedicated tools (tool called "ODBC Data Source +Administrator") and give a name to that connection. This name is then +used as database name when accessing from a client via ODBC. + +#### Linux + +Configure ODBC driver for selected database (manually or with +'ODBCConfig'). ODBC drivers are defined in /etc/odbcinst.ini. Here an +example: + +```bash + [PostgreSQL] + Description     = ODBC for PostgreSQL + Driver          = /usr/lib/libodbcpsql.so + Setup           = /usr/lib/libodbcpsqlS.so + FileUsage       = 1 +``` + +Create DSN (data source name). The DSN is used as database name in db.\* +modules. Then DSN must be defined in $HOME/.odbc.ini (for this user +only) or in /etc/odbc.ini for (for all users) \[watch out for the +database name which appears twice and also for the PostgreSQL protocol +version\]. Omit blanks at the beginning of lines: + +```bash + [grass6test] + Description             = PostgreSQL + Driver                  = PostgreSQL + Trace                   = No + TraceFile               = + + Database                = grass6test + Servername              = localhost + UserName                = neteler + Password                = + Port                    = 5432 + Protocol                = 8.0 + + ReadOnly                = No + RowVersioning           = No + ShowSystemTables        = No + ShowOidColumn           = No + FakeOidIndex            = No + ConnSettings            = +``` + +Configuration of an DSN without GUI is described on +, but odbc.ini and .odbc.ini may +be created by the 'ODBCConfig' tool. You can easily view your DSN +structure by 'DataManager'. Configuration with GUI is described on + + +To find out about your PostgreSQL protocol, run: + +```bash +psql -V +``` + +### Using the ODBC driver + +Now create a new database if not yet existing: + +```bash +db.createdb driver=odbc database=grass6test +``` + +To store a table 'mytable.dbf' (here: in current directory) into +PostgreSQL through ODBC, run: + +```bash +db.connect driver=odbc database=grass6test +db.copy from_driver=dbf from_database=./ from_table=mytable \ + to_driver=odbc to_database=grass6test to_table=mytable +``` + +Next link the map to the attribute table (now the ODBC table is used, +not the dbf file): + +```bash +v.db.connect map=mytable.shp table=mytable key=ID \ + database=grass6test driver=odbc +v.db.connect -p +``` + +Finally a test: Here we should see the table columns (if the ODBC +connection works): + +```bash +db.tables -p +db.columns table=mytable +``` + +Now the table name 'mytable' should appear. +Doesn't work? Check with 'isql \' if the ODBC-PostgreSQL +connection is really established. + +Note that you can also connect mySQL, Oracle etc. through ODBC to GRASS. + +You can also check the vector map itself concerning a current link to a +table: + +```bash +v.db.connect -p mytable.shp +``` + +which should print the database connection through ODBC to the defined +RDBMS. + +## SEE ALSO + +*[db.connect](db.connect.md), [v.db.connect](v.db.connect.md), [unixODBC +web site](https://www.unixodbc.org), [SQL support in GRASS GIS](sql.md)* diff --git a/db/drivers/ogr/grass-ogr.md b/db/drivers/ogr/grass-ogr.md new file mode 100644 index 00000000000..60fefbc365c --- /dev/null +++ b/db/drivers/ogr/grass-ogr.md @@ -0,0 +1,7 @@ +This driver is principally only used by *[v.external](v.external.md)*. + +## SEE ALSO + +*[SQL support in GRASS GIS](sql.md)* + +*[v.external](v.external.md)* diff --git a/db/drivers/postgres/grass-pg.md b/db/drivers/postgres/grass-pg.md new file mode 100644 index 00000000000..2a935f0f5df --- /dev/null +++ b/db/drivers/postgres/grass-pg.md @@ -0,0 +1,134 @@ +PostgreSQL database driver enables GRASS to store vector attributes in +PostgreSQL server. + +## Creating a PostgreSQL database + +A new database is created with `createdb`, see the [PostgreSQL +manual](https://www.postgresql.org/docs/manuals/) for details. + +## Connecting GRASS to PostgreSQL + +```bash +# example for connecting to a PostgreSQL server: +db.connect driver=pg database=mydb +db.login user=myname password=secret host=myserver.osgeo.org # port=5432 +db.connect -p +db.tables -p +``` + +### Username and password + +From the [PostgresQL +manual](https://www.postgresql.org/docs/10/static/libpq-pgpass.html): + +The file *.pgpass* in a user's home directory can contain passwords to +be used if the connection requires a password (and no password has been +specified otherwise). On Microsoft Windows the file is named +*%APPDATA%\postgresql\pgpass.conf* (where *%APPDATA%* refers to the +Application Data subdirectory in the user's profile). Alternatively, a +password file can be specified using the connection parameter passfile +or the environment variable PGPASSFILE. This file should contain lines +of the following format: + +```bash +hostname:port:database:username:password +``` + +## Supported SQL commands + +All SQL commands supported by PostgreSQL. It's not possible to use +C-like escapes (with backslash like \n etc) within the SQL syntax. + +## Operators available in conditions + +All SQL operators supported by PostgreSQL. + +## Adding an unique ID column + +Import vector module require an unique ID column which can be generated +as follows in a PostgreSQL table: + +```bash +db.execute sql="ALTER TABLE mytable ADD ID integer" +db.execute sql="CREATE SEQUENCE mytable_seq" +db.execute sql="UPDATE mytable SET ID = nextval('mytable_seq')" +db.execute sql="DROP SEQUENCE mytable_seq" +``` + +## Attribute import into PostgreSQL + +CSV import into PostgreSQL: + +```bash +\h copy +COPY t1 FROM 'filename' USING DELIMITERS ','; +``` + +## Geometry import from PostgreSQL table into GRASS + +*[v.in.db](v.in.db.md)* creates a new vector (points) map from a +database table containing coordinates. See [here](v.in.db.md) for +examples. + +## PostGIS: PostgreSQL with vector geometry + +[PostGIS](https://postgis.net/): adds geographic object support to +PostgreSQL. + +### Example: Import from PostGIS + +In an existing PostGIS database, create the following table: + +```bash +CREATE TABLE test +( + id serial NOT NULL, + mytime timestamp DEFAULT now(), + text varchar, + wkb_geometry geometry, + CONSTRAINT test_pkey PRIMARY KEY (id) +) WITHOUT OIDS; + +# insert value +INSERT INTO test (text, wkb_geometry) + VALUES ('Name',geometryFromText('POLYGON((600000 200000,650000 + 200000,650000 250000,600000 250000,600000 200000))',-1)); + +# register geometry column +select AddGeometryColumn ('postgis', 'test', 'geometry', -1, 'GEOMETRY', 2); +``` + +GRASS can import this PostGIS polygon map as follows: + +```bash +v.in.ogr input="PG:host=localhost dbname=postgis user=neteler" layer=test \ + output=test type=boundary,centroid +v.db.select test +v.info -t test +``` + +#### Geometry Converters + +- [PostGIS with + shp2pgsql](https://postgis.net/workshops/postgis-intro/loading_data.html#loading-with-shp2pgsql): + `shp2pgsql -D lakespy2 lakespy2 test > lakespy2.sql` +- [e00pg](https://e00pg.sourceforge.net/): E00 to PostGIS filter, see + also *[v.in.e00](v.in.e00.md)*. +- GDAL/OGR [ogrinfo and ogr2ogr](https://gdal.org/): GIS vector format + converter and library, e.g. ArcInfo or SHAPE to PostGIS. + `ogr2ogr -f "PostgreSQL" shapefile ??` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.execute](db.execute.md)* + +[Database management in GRASS GIS](databaseintro.md) +[Help pages for database modules](database.md) +[SQL support in GRASS GIS](sql.md) + +## REFERENCES + +- [PostgreSQL web site](https://www.postgresql.org/) +- [pgAdmin graphical user interface](https://www.pgadmin.org/) +- [GDAL/OGR PostgreSQL driver + documentation](https://gdal.org/en/stable/drivers/vector/pg.html) diff --git a/db/drivers/sqlite/grass-sqlite.md b/db/drivers/sqlite/grass-sqlite.md new file mode 100644 index 00000000000..09cc4c8f631 --- /dev/null +++ b/db/drivers/sqlite/grass-sqlite.md @@ -0,0 +1,54 @@ +The SQLite driver is the default DBMI backend. + +## Creating a SQLite database + +GRASS is automatically creating the SQLite database if it is not yet +existing when the first table is created in the SQLite database. It is +sufficient to define the connection (see next step). + +## Connecting GRASS to SQLite + +The database name 'sqlite.db' is at user's choice. Also the file storage +location can be freely chosen. If the database does not exist, it will +be automatically created when database content is created: + +```bash +# example for storing DB in mapset directory (keep single quotes): +db.connect driver=sqlite database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db' +db.connect -p +``` + +## Supported SQL commands + +All SQL commands supported by SQLite (for limitations, see SQLite help +page: [SQL As Understood By SQLite](https://www.sqlite.org/lang.html) +and [Unsupported SQL](https://www.sqlite.org/omitted.html)). + +## Operators available in conditions + +All SQL operators supported by SQLite. + +## Browsing table data in DB + +A convenient SQLite front-end is +[sqlitebrowser](https://sqlitebrowser.org/). To open a DB file stored +within the current mapset, the following way is suggested (corresponds +to above database connection): + +```bash +# fetch GRASS variables as shell environment variables: +eval `g.gisenv` +# use double quotes: +sqlitebrowser "$GISDBASE/$LOCATION_NAME/$MAPSET"/sqlite/sqlite.db +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.execute](db.execute.md), +[db.select](db.select.md)* + +*[SQL support in GRASS GIS](sql.md)* + +*[SQLite web site](https://www.sqlite.org), [SQLite +manual](https://www.sqlite.org/quickstart.html), [sqlite - Management +Tools](https://www2.sqlite.org/cvstrac/wiki?p=ManagementTools)* diff --git a/display/d.barscale/d.barscale.md b/display/d.barscale/d.barscale.md new file mode 100644 index 00000000000..8d94ef53826 --- /dev/null +++ b/display/d.barscale/d.barscale.md @@ -0,0 +1,24 @@ +## DESCRIPTION + +*d.barscale* displays a barscale on the graphics monitor at the given +screen coordinates. If no coordinates are given it will draw the +barscale in the bottom left of the display. + +The barscale can drawn in a number of styles (see **style** parameter +for their previews). + +## NOTE + +*d.barscale* will not work with Lat/Lon coordinate reference system as +the horizontal scale distance changes with latitude. Try +*[d.grid](d.grid.md)* instead. + +## SEE ALSO + +*[d.graph](d.graph.md), [d.grid](d.grid.md), [d.legend](d.legend.md), +[d.northarrow](d.northarrow.md), [g.region](g.region.md)* + +## AUTHORS + +Unknown, from USACE/CERL. +Major rewrite for GRASS 7 by Hamish Bowman diff --git a/display/d.colorlist/d.colorlist.md b/display/d.colorlist/d.colorlist.md new file mode 100644 index 00000000000..b44ab2d36c8 --- /dev/null +++ b/display/d.colorlist/d.colorlist.md @@ -0,0 +1,13 @@ +## DESCRIPTION + +*d.colorlist* report the available color names. The list contains all +available display colors with a configurable separator (default is +comma). + +## SEE ALSO + +*[r.colors](r.colors.md)* + +## AUTHOR + +Andreas Lange diff --git a/display/d.colortable/d.colortable.md b/display/d.colortable/d.colortable.md new file mode 100644 index 00000000000..72429c5feb9 --- /dev/null +++ b/display/d.colortable/d.colortable.md @@ -0,0 +1,58 @@ +## DESCRIPTION + +*d.colortable* is used to display the color table associated with a +raster map in the active frame on the graphics monitor. The **map** name +should be an available raster map in the user's current mapset search +path and location. + +If the *values* of both **lines** and **columns** are not specified by +the user, *d.colortable* divides the active frame equally among the +number of categories present in the named raster map. If one option is +specified, the other is automatically set to accommodate all categories. +If both are specified, as many categories as possible are displayed. + +If the user specifies the name of a map on the command line but does not +specify the values of other parameters, parameter default values will be +used. Alternately, if the user types simply *d.colortable* on the +command line without any program arguments, the program will prompt the +user for parameter settings using the standard GRASS parser interface. + +## EXAMPLE + +The user running the command: + +```bash +d.colortable map=soils color=red lines=1 columns=3 +``` + +would see the active graphics frame divided into three columns extending +the full frame height. The lines dividing the color table associated +with the *soils* map would be displayed in red. The user would see, at +most, only three of the colors from the *soils* color table displayed in +the active frame (because the user requested that this frame be divided +into three sections). + +## NOTES + +If the user wishes to display the entire color table associated with a +map, the user should either stipulate a number of lines (rows) and +columns (cols) sufficient to accommodate the number of categories in the +map's color table, or fail to assign values to one or both of **lines** +and/or **columns**. If the user runs *d.colortable* using the default +number of lines and columns (the full graphics frame), all categories +from the map's color table will be displayed. However, if the user +requests that the color table associated with a map which has 10 data +categories be displayed in a graphics frame with only 3 lines (rows) and +2 columns (a total of six cells), only six of the ten map categories +will be displayed. + +The user should run *[d.erase](d.erase.md)* between runs of +*d.colortable* to avoid confusion. + +## SEE ALSO + +*[d.erase](d.erase.md), [d.legend](d.legend.md), [d.rast](d.rast.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.erase/d.erase.md b/display/d.erase/d.erase.md new file mode 100644 index 00000000000..410a57f5bd4 --- /dev/null +++ b/display/d.erase/d.erase.md @@ -0,0 +1,14 @@ +## DESCRIPTION + +*d.erase* erases the contents of the active graphics frame, and replaces +it with the color black (by default) or by whatever color is specified +by the user. + +## SEE ALSO + +*[d.mon](d.mon.md), [d.redraw](d.redraw.md), [d.rast](d.rast.md), +[d.vect](d.vect.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.extract/d.extract.md b/display/d.extract/d.extract.md new file mode 100644 index 00000000000..4b2bc4aca51 --- /dev/null +++ b/display/d.extract/d.extract.md @@ -0,0 +1,23 @@ +## DESCRIPTION + +*d.extract* allows a user to graphically select vector objects from an +existing vector map and creates a new map containing only the selected +objects. + +## EXAMPLE + +### Graphically extract roads from a roads map + +```bash +d.mon x0 +d.vect roads +d.extract input=roads output=interstate +``` + +## SEE ALSO + +*[v.extract](v.extract.md)* + +## AUTHORS + +Radim Blazek, Markus Neteler diff --git a/display/d.font/d.font.md b/display/d.font/d.font.md new file mode 100644 index 00000000000..32c7e3e3d88 --- /dev/null +++ b/display/d.font/d.font.md @@ -0,0 +1,55 @@ +## DESCRIPTION + +*d.font* allows the user to select use of a specific text font for +display of text on the graphics monitor. If the user does not specify a +font when using other GRASS programs that display text, the font type +*romans* is used by default. + +The user can run this program either non-interactively or interactively. +If the user specifies a font type name on the command line the program +will run non-interactively. Alternately, the user can simply type +**d.font** on the command line; in this case, the program will prompt +the user for a display text font type. + +**Parameter:** + +**font=***name* +Name of a font type, from among the font types italicized below. +Default: *romans* +Options: (italized) +*cyrilc* Cyrillic +*gothgbt* Gothic Great Britain triplex +*gothgrt* Gothic German triplex +*gothitt* Gothic Italian triplex +*greekc* Greek complex +*greekcs* Greek complex script +*greekp* Greek plain +*greeks* Greek simplex +*italicc* Italian complex +*italiccs* Italian complex small +*italict* Italian triplex +*romanc* Roman complex +*romancs* Roman complex small +*romand* Roman duplex +*romanp* Roman plain +*romans* Roman simplex +*romant* Roman triplex +*scriptc* Script complex +*scripts* Script simplex + +## NOTES + +The font type *romans* is the fastest font type to display to the +graphics monitor. + +## SEE ALSO + +*[d.text](d.text.md)* +*[d.title](d.title.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory + +*d.font* uses the public domain version of the Hershey Fonts created by +Dr. A.V. Hershey while working at the U.S. National Bureau of Standards. diff --git a/display/d.fontlist/d.fontlist.md b/display/d.fontlist/d.fontlist.md new file mode 100644 index 00000000000..9a340fc438e --- /dev/null +++ b/display/d.fontlist/d.fontlist.md @@ -0,0 +1,12 @@ +## DESCRIPTION + +*d.fontlist* outputs a list of available fonts for use with GRASS +display commands. + +## SEE ALSO + +*[d.text](d.text.md)* + +## AUTHOR + +Glynn Clements diff --git a/display/d.geodesic/d.geodesic.md b/display/d.geodesic/d.geodesic.md new file mode 100644 index 00000000000..0c896591d40 --- /dev/null +++ b/display/d.geodesic/d.geodesic.md @@ -0,0 +1,50 @@ +## DESCRIPTION + +*d.geodesic* displays a geodesic line in the active frame on the user's +graphics monitor. This is also known as the great circle line and traces +the shortest distance between two user-specified points on the curved +surface of a longitude/latitude data set. The two coordinate locations +named must fall within the boundaries of the user's current geographic +region. + +## OPTIONS + +By default black line color and red text color will be used. + +By indicating the starting and ending coordinates of the geodesic, the +line and its length (by default in meters) are displayed to the +graphical output. If the text color is set to *none*, the great circle +distance is not displayed. + +## EXAMPLE + +A geodesic line if shown over the political map of the world +(demolocation dataset): + +```bash +g.region vector=country_boundaries -p +d.mon wx0 +d.vect country_boundaries type=area +# show additionally a 20 degree grid +d.grid 20 + +d.geodesic coordinates=55:58W,33:18S,26:43E,60:37N \ + line_color=yellow text_color=red units=kilometers +``` + + +*Geodesic line (great circle line)* + +## NOTES + +This program works only with longitude/latitude coordinate system. + +## SEE ALSO + +*[d.rhumbline](d.rhumbline.md), [d.grid](d.grid.md), +[m.measure](m.measure.md)* + +## AUTHOR + +Michael Shapiro, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.graph/d.graph.md b/display/d.graph/d.graph.md new file mode 100644 index 00000000000..722ee14a019 --- /dev/null +++ b/display/d.graph/d.graph.md @@ -0,0 +1,178 @@ +## DESCRIPTION + +*d.graph* draws graphics that are described either from standard input +(default), or within a file (if an **input** file name is identified on +the command line). If graphics commands are entered from standard input, +a *CTRL-d* is used to signal the end of input to *d.graph*. Coordinates +are given either as a percentage of frame height and width (default) or +in geographic coordinates (with the **-m** flag). + +The program can be run interactively or non-interactively. The user can +run the program completely non-interactively by specifying the name of a +graphics file containing the *d.graph* graphics commands. If run +non-interactively the *d.graph* command is saved to the display's dedraw +history. The user can also elect to run the program partially +interactively, by specifying any/all of the parameters *except* the +graphics file **input=***name* parameter on the command line. In this +case, *d.graph* will expect the user to input *d.graph* graphics +commands from standard input (i.e., the keyboard) and will (silently) +prompt the user for these graphics commands. + +Alternately, the user can simply type **d.graph** on the command line, +and be prompted for the values of all parameters. In this case, the user +is presented with the standard GRASS GUI interface. + +The default coordinate system used is 0-100 percent of the active frame +in x and similarly 0-100 in y, regardless of the graphics monitor +display frame size and aspect. The (0,0) location is the lower left +corner of the active graphics monitor display frame. All values may be +floating point. If the **-m** flag is given, geographic coordinates will +be used instead. + +## COMMANDS + +The graphics language is simple, and uses the following commands: + +\[ [\#](#comment) \| [move](#move) \| [draw](#draw) \| +[polygon](#polygon) \| [polyline](#polyline) \| [color](#color) \| +[text](#text) \| [size](#size) \| [symbol](#symbol) \| +[rotation](#rotation) \| [icon](#icon) \| [width](#width) \] + +**\#** *comment* +A line of comment which is ignored in the processing. + +**move** *xpos ypos* +The current location is updated to *xpos ypos*. Unless the **-m** flag +is used, values are stated as a percent of the active display frame's +horizontal (*xpos*) and vertical (*ypos*) size, and may be floating +point values. Values are between 0-100. **Note.** A space must separate +*xpos* and *ypos*. + +**draw** *xpos ypos* +A line is drawn in the current color from the current location to the +new location *xpos ypos*, which then becomes the current location. +Unless the **-m** flag is used, values are stated as a percent of the +active display frame's horizontal (*xpos*) and vertical (*ypos*) size, +and may be floating point values. Values are between 0-100. **Note.** A +space must separate *xpos* and *ypos*. + +**polygon** +   *xpos ypos* +   *xpos ypos* +  ... +The coordinates appearing beneath the word *polygon*, one pair per line, +circumscribe a polygon that is to be filled with the current color. + +**polyline** +   *xpos ypos* +   *xpos ypos* +  ... +The coordinates appearing beneath the word *polyline*, one pair per +line, circumscribe a polygon that is not to be filled with color. + +**color** *color* +Sets the current color to that stated; subsequent graphics will be drawn +in the stated color, until the current color is set to a different +color. Options are *red*, *orange*, *yellow*, *green*, *blue*, *indigo*, +*violet*, *brown*, *magenta*, *gray*, *white*, *black*, an R:G:B triplet +(separated by colons), or the word "none" (draws in the default +background color). + +**text** *line-of-text* +The stated text is drawn at the current location using the current +color, and the new current location is then positioned at the end of the +text string. + +**size** *xper yper* +Subsequent text will be drawn such that the text is *xper* percent of +the graphics monitor display frame wide and *yper* percent of the frame +high. By default, the text size is set to 5 percent of the active +frame's width and 5 percent of the frame's height. If only one value is +given, then that value will be used for both x and y scaling. +**Note.** A space must separate *xper* and *yper*. + +**symbol** *type size xper yper \[line_color \[fill_color\]\]* +A symbol is drawn at the given size on the display monitor. The *xper* +and *yper* options define the center of the icon and are given as a +percentage of the display frame (`0,0` is lower left). The symbol can be +any of those stored in `$GISBASE/etc/symbol/` (e.g. *basic/circle*) or +stored in the user's mapset directory in the form +`$MAPSET/symbol/`*type/name*. The colors may be either a standard color +name, an R:G:B triplet, or "none". If using an R:G:B triplet, each color +value can range from 0-255. If not specified the default *line_color* is +black and the default *fill_color* is grey. + +**rotation** *angle* +Subsequent text and symbols will be drawn such that they are rotated +*angle* degrees counter-clockwise from east. + +**icon** *type size x y* +Draws an icon of types *o*, *x*, or *+* with specified *size* (in %) at +location *x,y*. Note: type *o* designates a square. + +**width** *value* +Subsequent lines (including non-FreeType text) will be drawn with the +given pixel thickness. +The default value is 0. + +## EXAMPLES + +For an example use of *d.graph*, examine the contents of the command +file *[grass_logo.txt](grass_logo.txt)* located in the *d.graph* source +code directory. It will draw the CERL GRASS logo using the *d.graph* +graphing commands stored in the file. Note that the coordinates in the +*[grass_logo.txt](grass_logo.txt)* file were taken directly off an image +drawn by hand on graph paper. + +A dynamic example can be found in the *d.polar* shell script. + +### Draw a "star" symbol at a given map coordinate + +```bash +echo "symbol basic/star 20 2264417 5413182 black red" | d.graph -m +``` + +### Split the screen into quadrants + +```bash +d.frame -s full_screen + +d.graph << EOF + color 80:80:120 + polygon + 0 49.75 + 0 50.25 + 100 50.25 + 100 49.75 + polygon + 49.85 0 + 50.15 0 + 50.15 100 + 49.85 100 +EOF +``` + +## NOTES + +*d.graph* remembers the last screen location (*xpos ypos*) to which the +user moved, even after the user erases the display frame. If the user +runs *d.graph* repeatedly, and wishes to start anew with the default +(xpos ypos) screen location, the user should *clear* the display frame +between runs of *d.graph*. + +## LIMITATIONS + +There are no automated ways of generating graphic images. It is +anticipated that GRASS user sites will write programs to convert output +from a resident graphics editor into GRASS *d.graph* format. (e.g. EPS +-\> *d.graph*, perhaps with the help of a +[pstoedit](http://www.pstoedit.net/) plugin) + +## SEE ALSO + +*[d.font](d.font.md), [d.labels](d.labels.md), [d.polar](d.polar.md), +[d.text](d.text.md), [d.where](d.where.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.grid/d.grid.md b/display/d.grid/d.grid.md new file mode 100644 index 00000000000..af090081dc5 --- /dev/null +++ b/display/d.grid/d.grid.md @@ -0,0 +1,80 @@ +## DESCRIPTION + +*d.grid* overlays a grid of user-defined size and color in the active +display frame on the graphics monitor. The grid can be created as a +standard rectangular grid or a geographic grid. + +If the user provides a **-g** flag a geographic (projected) grid will be +drawn. With the **-g** flag the **size** argument accepts both decimal +degrees and colon separated ddd:mm:ss coordinates (eg. `00:30:00` for +half of a degree). A geographic grid cannot be drawn for a +*latitude/longitude* or *XY* projection. + +Colors may be standard named GRASS colors (red, green, aqua, etc.) or a +numerical R:G:B triplet, where component values range from 0-255. Grid +color can be set with option **color**. Options **text_color** and +**bgcolor** set the color of the text and its background. + +The grid drawing may be turned off by using the **-n** flag. +The border drawing may be turned off by using the **-b** flag. +The coordinate text may be turned off by using the **-t** flag. + +To draw grid lines at different intervals, e.g. at high latitudes, you +can run the module twice, once with **direction**=*east-west* at one +interval **size**, and again with **direction**=*north-south* at another +interval **size**. + +## EXAMPLES + +To draw a red geographic grid with 30 minute grid spacing, run one of +the following commands: + +```bash +d.grid -g size=00:30:00 color=red +``` + +or + +```bash +d.grid -g size=0.5 color=255:0:0 +``` + +
+ + +*Figure: Showing a geographic grid in red line color* + +
+ +To draw a blue standard rectangular grid at a 500 (meter) spacing run +the following: + +```bash +d.grid size=500 color=blue +``` + +
+ + +*Figure: Showing a rectangular grid in blue line color* + +
+ +## SEE ALSO + +*[d.barscale](d.barscale.md), [d.legend](d.legend.md), +[d.geodesic](d.geodesic.md), [d.rhumbline](d.rhumbline.md), +[d.erase](d.erase.md), [d.frame](d.frame.md), [d.rast](d.rast.md), +[v.mkgrid](v.mkgrid.md)* + +## AUTHORS + +James Westervelt, U.S. Army Construction Engineering Research +Laboratory +Geogrid support: Bob Covill +Border support: Markus Neteler +Text and RGB support: Hamish Bowman +Background color implemented as part of GSoC 2016 by Adam Laza, CTU in +Prague diff --git a/display/d.his/d.his.md b/display/d.his/d.his.md new file mode 100644 index 00000000000..4c575d2e6b2 --- /dev/null +++ b/display/d.his/d.his.md @@ -0,0 +1,105 @@ +## DESCRIPTION + +*d.his* displays the result obtained by combining hue, intensity, and +saturation (HIS) values from user-specified input raster map layers. + +*HIS* stands for hue, intensity, and saturation. This program produces a +raster map layer providing a visually pleasing combination of hue, +intensity, and saturation values from two or three user-specified raster +map layers. + +The human brain automatically interprets the vast amount of visual +information available according to basic rules. Color, or *hue*, is used +to categorize objects. Shading, or *intensity*, is interpreted as +three-dimensional texturing. Finally, the degree of haziness, or +*saturation*, is associated with distance or depth. This program allows +data from up to three raster map layers to be combined into an image +which retains the original information in terms of *hue*, *intensity*, +and *saturation*. + +## OPTIONS + +This program can be run non-interactively or interactively. It will run +non-interactively if the user specifies on the command line the name of +a map containing hue values (**hue**), and the name(s) of map(s) +containing intensity values (**intensity**) and/or saturation values +(**saturation**). The resulting image will be displayed in the active +display frame on the graphics monitor. + +Alternately, the user can run the program interactively by typing +**d.his** without naming parameter values on the command line. In this +case, the program will prompt the user for parameter values using the +standard GRASS GUI interface. + +While any raster map layer can be used to represent the hue information, +map layers with a few very distinct colors work best. Only raster map +layers representing continuously varying data like elevation, aspect, +weights, intensities, or amounts can suitably be used to provide +intensity and saturation information. + +For example, a visually pleasing image can be made by using a watershed +map for the *hue* factor, an aspect map for the *intensity* factor, and +an elevation map for *saturation*. (The user may wish to leave out the +elevation information for a first try.) Ideally, the resulting image +should resemble the view from an aircraft looking at a terrain on a +sunny day with a bit of haze in the valleys. + +The **brighten** option does not truly represent a percentage, but +calling it that makes the option easy to understand, and it sounds +better than *Normalized Scaling Factor*. + +## THE PROCESS + +Each map cell is processed individually. First, the working color is set +to the color of the corresponding cell in the map layer chosen to +represent *hue*. Second, this color is multiplied by the *red* intensity +of that cell in the *intensity* map layer. This map layer should have an +appropriate gray-scale color table associated with it. You can ensure +this by using the color manipulation capabilities of +*[r.colors](r.colors.md)*. Finally, the color is made somewhat +gray-based on the *red* intensity of that cell in the *saturation* map +layer. Again, this map layer should have a gray-scale color table +associated with it. + +## NOTES + +The name is misleading. The actual conversion used is + +```bash + H.i.s + G.(1-s) + +where + + H is the R,G,B color from the hue map + i is the red value from the intensity map + s is the red value from the saturation map + G is 50% gray (R = G = B = 0.5) + +``` + +Either (but not both) of the intensity or the saturation map layers may +be omitted. This means that it is possible to produce output images that +represent combinations of *his, hi,* or *hs*. + +Users wishing to store the result in new raster map layers instead of +displaying it on the monitor should use the command *[r.his](r.his.md)*. + +## EXAMPLE + +```bash +g.region raster=elevation +r.relief input=elevation output=elevation_shaded_relief + +d.mon wx0 +d.his hue=elevation intensity=elevation_shaded_relief brighten=50 +``` + +## SEE ALSO + +*[d.colortable](d.colortable.md), [d.frame](d.frame.md), +[d.rgb](d.rgb.md), [d.shade](d.shade.md), [r.colors](r.colors.md), +[r.his](r.his.md), [i.his.rgb](i.his.rgb.md), [i.rgb.his](i.rgb.his.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.histogram/d.histogram.md b/display/d.histogram/d.histogram.md new file mode 100644 index 00000000000..bbcb1a875d2 --- /dev/null +++ b/display/d.histogram/d.histogram.md @@ -0,0 +1,64 @@ +## DESCRIPTION + +*d.histogram* displays the category-value distribution for a +user-specified raster map layer, in the form of a bar chart or a pie +chart. The display will be displayed in the active display frame on the +graphics monitor, using the colors in the raster map layer's color +table. The program determines the raster map's category value +distribution by counting cells. + +## NOTES + +*d.histogram* respects the current geographic region settings and the +current raster mask (if mask is active). + +*d.histogram* uses the colors in the map's color look-up table (i.e., +the map's *colr* or *colr2* file). + +## EXAMPLES + +Running the command below will generate the bar graph shown in the +figure: + +```bash +g.region raster=elevation -p +d.mon wx0 +d.histogram map=elevation +``` + +
+ + +*Figure: Bar graph histogram for elevation map* + +
+ +Running the command below will generate the pie graph shown in the +figure: + +```bash +g.region raster=landuse96_28m -p +d.histogram map=landuse96_28m style=pie +``` + +
+ + +*Figure: Pie graph histogram for landuse map* + +
+ +## SEE ALSO + +*[d.colortable](d.colortable.md), [d.frame](d.frame.md), +[d.graph](d.graph.md), [d.linegraph](d.linegraph.md), [d.mon](d.mon.md), +[d.polar](d.polar.md), [g.region](g.region.md), [r.stats](r.stats.md)* + +## AUTHOR + +Dave Johnson +DBA Systems, Inc. +10560 Arrowhead Drive +Fairfax, Virginia 22030 diff --git a/display/d.info/d.info.md b/display/d.info/d.info.md new file mode 100644 index 00000000000..dd701a36ace --- /dev/null +++ b/display/d.info/d.info.md @@ -0,0 +1,30 @@ +## DESCRIPTION + +*d.info* displays information about the active display monitor. Display +monitors are maintained by *[d.mon](d.mon.md)*. + +## EXAMPLES + +```bash +d.mon start=cairo + +d.info -r +rectangle: 0.000000 640.000000 0.000000 480.000000 +``` + +## NOTES + +Units are screen pixels (except for **-g** flag where map units are +used). +Where two numbers are given the format is: width, height. +Where four numbers are given the format is: left, right, top, bottom. + +Note: GRASS display pixel coordinates are measured from the top left. + +## SEE ALSO + +*[d.mon](d.mon.md), [d.vect](d.vect.md), [d.rast](d.rast.md)* + +## AUTHOR + +Glynn Clements diff --git a/display/d.labels/d.labels.md b/display/d.labels/d.labels.md new file mode 100644 index 00000000000..85dbf020057 --- /dev/null +++ b/display/d.labels/d.labels.md @@ -0,0 +1,33 @@ +## DESCRIPTION + +*d.labels* displays a *paint* label file in the active display frame on +the graphics monitor. Each label has components which determine the +text, the location of the text on the image, its size, and the +background for the text. This file can be generated with the +*[v.label](v.label.md)* program or simply created by the user as an +ASCII file (using a text editor) and placed in the appropriate directory +under the user's current mapset and project (i.e. +`$MAPSET/paint/labels/`). + +## NOTES + +Some of the information stored in the label file is unused by +*d.labels*. This extra information is used by such programs as +*[ps.map](ps.map.md)*. + +This module was formerly known as *d.paint.labels*. The the old version +of *d.labels* from GRASS 5, which provided interactive placement and +modification of paint labels, still needs to have its functionality +merged into this module. + +## SEE ALSO + +*[d.font](d.font.md)* +*[d.text](d.text.md)* +*[d.title](d.title.md)* +*[ps.map](ps.map.md)* +*[v.label](v.label.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.legend.vect/d.legend.vect.md b/display/d.legend.vect/d.legend.vect.md new file mode 100644 index 00000000000..f2cbd670a64 --- /dev/null +++ b/display/d.legend.vect/d.legend.vect.md @@ -0,0 +1,105 @@ +## DESCRIPTION + +*d.legend.vect* draws vector legend of currently displayed vector maps. + +Parameter **at** defines the screen position of upper-left legend +corner. Parameter **columns** defines the number of legend columns. User +can specify a title of the legend using parameter **title**. The font of +the title can be changed with **title_font**, **title_fontsize**. Flag +**-b** is used to draw background of specified color (**bgcolor**), +border color and border width (**border_color** and **border_width**). +Parameter **symbol_size** defines the size of line and area symbols. The +size of point symbols is based on currently set symbology of vector maps +using *[d.vect](d.vect.md)* or *[d.vect.thematic](d.vect.thematic.md)*. + +Module *d.vect.legend* supports subtitles (see section Notes). Their +font and font size can be set using parameters **sub_font** and +**sub_fontsize**. + +### Changing legend symbols and labels + +Symbols for vector areas and lines, and labels for individual vector +labels can be changed in the symbology setting of each vector map in +*[d.vect](d.vect.md)* or *[d.vect.thematic](d.vect.thematic.md)* module +(in Legend tab). Use its parameters **icon_area** and **icon_line** to +pick from available symbols. By using parameter **legend_label** of +*d.vect* module, users can change the default label, which is the map +name. + +### Modifying the order of legend entries and omitting certain vector maps from legend + +Modules *[d.vect](d.vect.md)* and +*[d.vect.thematic](d.vect.thematic.md)* have a flag **-s** which removes +the particular vector or thematic vector from vector legend. + +The order of entries is defined by the order in Layer Manager (if used +in GRASS GIS GUI). If that's not desired, one can export the legend file +into a text file using parameter **output**, change the order of entries +(see section Notes for format description) and then upload the modified +file with parameter **input**. Parameter **output** defines path to the +file where the internal legend file will be saved to, **input** defines +the input file which the vector legend will be based on (input file must +have correct format). + +## NOTES + +Module *d.legend.vect* draws vector legend based on legend file defined +in shell environment variable GRASS_LEGEND_FILE. This file is +automatically created and updated whenever *[d.vect](d.vect.md)* command +is used. User can create custom legend file and then use *export +GRASS_LEGEND_FILE=path/to/file* in shell. GRASS GUI and MONITORS create +the legend file automatically. By default the legend file is stored in +grassdata/project/mapset/.tmp/user directory (in case of d.mon deeper in +/monitor_name directory). + +Legend file has this format: + +```bash +label|symbol_name|size|color_type|feature_color|fill_color|line_width|geometry_type|feature_count +``` + +Color type can be 'lf' or 'ps'. Based on color type color columns are +interpreted as line color and fill colors (lf), or primary and secondary +colors (ps). Module d.vect always uses 'lf' and d.vect.thematic 'ps'. +Here is an example of legend file with subtitles: + +```bash +Infrastructure|||||||| +major roads|legend/line|5|lf|black|200:200:200|2|line|355 +bridges|extra/bridge|15|lf|black|black|1|point|10938 +Hydrology|||||||| +streams|legend/line_crooked|5|lf|30:144:255|200:200:200|3|line|8554 +water bodies|legend/area_curved|5|lf|none|30:144:255|1|area|27764 +``` + +![Example of subheadings used in vector +legend](d_legend_vect_subheadings.png) + +## EXAMPLES + +Open cairo monitor to render to file: + +```bash +g.region vector=nc_state +d.mon cairo +d.vect map=nc_state color=26:26:26 fill_color=229:229:229 width=2 legend_label="state boundaries" +d.vect map=urbanarea color=none fill_color=127:127:127 width=1 legend_label="urban areas" +d.vect map=railroads color=red width=1 +d.vect map=hospitals color=77:77:77 fill_color=0:187:0 width=1 icon=basic/cross3 size=10 +d.legend.vect -b at=2,40 title="Hospitals in North Carolina" symbol_size=26 fontsize=16 title_fontsize=20 +``` + +![d.legend.vect example](d_legend_vect.png) + +## SEE ALSO + +*[d.vect](d.vect.md), [d.vect.thematic](d.vect.thematic.md), +[d.legend](d.legend.md)* + +Check also Python module from AddOns: +*[d.vect.thematic2](https://grass.osgeo.org/grass8/manuals/addons/d.vect.thematic2.html)* + +## AUTHORS + +Adam Laza, during GSoC 2016 Mentors: Anna Petrasova, Vaclav Petras, +Martin Landa diff --git a/display/d.legend/d.legend.md b/display/d.legend/d.legend.md new file mode 100644 index 00000000000..77d11b0795c --- /dev/null +++ b/display/d.legend/d.legend.md @@ -0,0 +1,153 @@ +## DESCRIPTION + +*d.legend* displays a legend for a user-specified raster map or 3D +raster map layer in the active frame on the graphics monitor. + +The legend's default size is based on the dimensions of the active +frame, specifically its height. *d.legend* will only obscure those +portions of the active frame that directly underlie the legend. + +## NOTES + +When using the **at** to size & place the legend, a user may create a +horizontal legend by making the box wider than it is tall. + +Raster maps based on floating point values will display smoothed, from +greatest to smallest value, while categorical raster maps will display +in order, from top to bottom. Horizontal legends will always be +smoothed. If the box is defined with inverted y-values or an inverted +**range**, the legend will automatically flip. If this is not the +desired result, the **-f** flag may be used to flip it back. + +If the user attempts to display a very long legend in a relatively short +display frame, the legend may appear in unreadably small text, or even +revert to a smooth gradient legend. Use the **lines**, **thin**, +**use**, **range**, and/or **-n** options to reduce the number of +categories to be displayed, or the **-s** flag to force a smooth +gradient legend. + +The **lines** option will display the first number of categories, as +defined by *value*, contained in the raster map. When used with the +**-n** flag, it takes on a new meaning: "up to category \#". When used +with both **thin** and the **-n** flag, its meaning becomes more +obscure. When using **lines**, auto-scaled text similar to "4 of 16 +categories" will be placed at the bottom of the legend. + +The **thin** option sets the thinning factor. For raster maps with a 0th +category, **thin=***10* gives cats \[0,10,20,...\]. For raster maps +starting at category 1, **thin=***10* gives cats \[1,11,21,...\]. + +The **use** option lets the user create a legend made up of arbitrary +category values. e.g. **use=***1000,100,10,0,-10,-100,-1000* + +The **range** option lets the user define the minimum and maximum +categories to be used in the legend. It may also be used to define the +limits of a smooth gradient legend created from a raster containing +floating point values. Note the color scale will remain faithful to the +category values as defined with *[r.colors](r.colors.md)*, and the +**range** may be extended to the limits defined by the +*[r.colors](r.colors.md)* color map. + +The flag **-n** is useful for categorial maps, as it suppresses the +drawing of non-existing categories (otherwise the full range is shown). + +Vertical legends produced with *d.legend* will place text labels to the +right of the legend box, horizontal legends will place text below. This +text will be auto-scaled to fit within the frame, reducing the size of +the legend if necessary. Legends positioned with the **at** option will +not auto-scale text, in order to provide more control to the user. +Smaller text may be obtained in this case by reducing the height of the +box or by using the **fontsize** option. The **-c** and **-v** flags may +be used to suppress the display of category numbers and labels +respectively, or used together to suppress all text of categorial raster +maps. + +The text produced from floating-point raster maps will automatically +create output with a meaningful number of significant digits. For very +small values, numbers will be expressed in scientific notation, +e.g. "1.7e-9". Option **digits** can be used to determine how many +digits after decimal point will be displayed. + +When the **-d** flag is used to display a histogram distribution along +side the smoothed gradient legend, note that the statistics are +calculated on the *current computational region* settings set by +*g.region*. The default **range** however covers the entire natural +bounds of the input map. If the histogram appears empty, check your +region settings. + +If the raster map's *units* metadata has been set with the *r.support* +module then it will be displayed along side the legend. + +The option **title** will display the custom title at the top of the +legend. In case of vertical legend the title is aligned to the left edge +of legend, in case of horizontal legend the title is aligned to the +center. **title_fontsize** can be used to set the size of legend title. +By default the legend title font size is the same as labels font size. + +There are different options to customize displayed labels. The +**labelnum** set the number of labels which are displayed in regular +intervals. The **label_values** will specify the values where the labels +will be displayed. The **label_step** will display labels at values +which are divisible by this value. + +The flag **-t** will show ticks at labels. + +The flag **-b** will show the background. Options **bgcolor** and +**border_color** can be used to choose the color of border and +background fill. + +The flag **-l** will switch to logarithmic scale. In case this flag is +used, the provided step in **label_step** is interpreted in the +logarithmic space. + +## EXAMPLE + +Displaying the legend along with a histogram (North Carolina Sample +dataset): + +```bash +g.region raster=elevation -p +d.rast elevation +d.legend -d elevation +``` + + + +Displaying the legend with custom labels and background: + +```bash +g.region raster=elevation -p +d.rast elevation +d.legend raster=elevation -t label_step=20 label_values=108 title=Legend -b bgcolor=255:255:204 border_color=gray +``` + + + +Displaying the legend with logarithmic scale: + +```bash +g.region raster=elevation -p +r.watershed -a elevation=elevation threshold=1000 accumulation=flowacc +d.rast flowacc +d.legend raster=flowacc -t -l label_step=1 +``` + + + +## SEE ALSO + +*[d.barscale](d.barscale.md), [d.colortable](d.colortable.md), +[d.font](d.font.md), [d.grid](d.grid.md), [d.rast](d.rast.md), +[d.rast.leg](d.rast.leg.md), [d.text](d.text.md), +[d.vect.thematic](d.vect.thematic.md), [r.reclass](r.reclass.md), +[r.stats](r.stats.md), [r3.stats](r3.stats.md)* + +## AUTHORS + +Bill Brown, U.S. Army Construction Engineering Research Laboratories +Late 2002: Rewrite of much of the code. Hamish Bowman, Otago University, +New Zealand +Additional improvements from various authors diff --git a/display/d.linegraph/d.linegraph.md b/display/d.linegraph/d.linegraph.md new file mode 100644 index 00000000000..f1274a3552a --- /dev/null +++ b/display/d.linegraph/d.linegraph.md @@ -0,0 +1,146 @@ +## DESCRIPTION + +*d.linegraph* is a module to draw simple x,y line graphs (plots) based +on numerical data contained in separate files. + +### Data format + +The X and Y data files for the graph are essentially a column of numbers +in each file, with one input number per line. The program expects that +each X value will have a corresponding Y value, therefore the number of +lines in each data input file should be the same. Essentially, the X +data becomes the X axis reference to which the Y data is plotted as a +line. Therefore, the X data should be a monotonically increasing +progression of numbers (i.e. "1,2,3,..."; "0, 10, 100, 1000,..."; +"...-5,-1,0,1,5..."). If multiple Y data files are used, the Y axis +scale will be based on the range of minimum and maximum values from all +Y files, then all Y data given will be graphed according to that Y +scale. Therefore, if multiple Y data inputs are used with dissimilar +units, the graph produced comparing the two will be deceptive. + +### File inputs + +If the **directory** option is provided, the paths to files can (and +should) be only relative paths to these files. While this is not +recommended for scripting, it can be advantageous when typing the paths +manually. For example when all files are stored in the directory +`/home/john/data`, the user can provide the following in the command +line: + +```bash +d.linegraph directory=/home/john/data x_file=x.txt y_file=y1.txt,y2.txt +``` + +### Managing colors + +The user can specify the **y_color** option, the **color_table** option +or just leave the defaults to influence the color of the plotted lines. + +Colors specified by **y_color** option are used for drawing the lines in +the graph. If multiple Y data files are used, an equal number of colors +may be used to control the colors of the lines. Colors will be assigned +to Y data in respect to the sequence of instantiation on the command +line. It can be one of GRASS GIS named colors or the RGB values from +0-255 separated by colons (RRR:GGG:BBB). + +Alternatively, the user can use the **color_table** option to specify +one of the GRASS GIS predefined color tables. + +By default, a series of colors will be chosen by the module if none are +provided upon invocation. The order of default colors is red, green, +violet, blue, orange, gray, brown, magenta, white, and indigo. The user +is advised not to rely on the order of default colors but to either use +the **y_color** or the **color_table** option to obtain predictable and +reproducible results. + +The color to be used for titles, axis lines, tics, and scale numbers is +determined by the **title_color** option. The user can provide one of +the GRASS GIS named colors (such as gray, white, or black) or use the +GRASS GIS colon-separated format for RGB (RRR:GGG:BBB). + +### Titles, labels, and tics + +The **title** option specifies the text for the title of the graph. It +will be centered over the top of graph. The **x_title** option is a text +to describe data for X axis. It will be centered beneath the graph. +Default is no text unless there is a need for a unit descriptor +determined by the *d.linegraph* module, then string such as "in +hundreds" is generated. The **y_title** option is a text to describe +data for Y axis. It will be centered beneath the X data description. +Similarly, to the **x_title** option, default is no text unless there is +a need for an auto-generated description. In the case of graphs with +multiple lines (multiple inputs for Y axis), user may wish to use more +specific text placement using the *[d.text](d.text.md)* or +*[v.label](v.label.md)* programs. + +## NOTES + +For historical reasons, the *d.linegraph* module accepts titles of more +than one word where the underscore character ("\_") is used to represent +spaces (" "). For example "Census_data_1990" would be printed over the +graph as "Census data 1990". The use of underscores is not necessary to +use as long as the parameter is quoted in the command line. In general, +use of underscores is not recommended and there is no need to use it at +all in the GUI or when using *d.linegraph* in Python scripts. + +The way the program locates and labels tic marks is less than perfect: + +1) although distances between Y tics are proportional to the value, they +are not proportional on the X axis; +2) decimal values between -1 and 1 can be printed on the X axis, but not +on Y. (With respect to the later, the input for Y values can all be +multiplied by a factor of 10 before graphing). + +Depending on the user's needs, it might be easier or more appropriate to +use a 3rd party tool such as xgraph, gnuplot, Matplotlib in Python, or R +instead of *d.linegraph*. For a more general solution for plotting in +GRASS GIS, the user is advised to use the *[d.graph](d.graph.md)* +module. + +## EXAMPLE + +The following can be executed in Bash to create the input data for this +example. The user can just create these files in a text editor, save +them and specify path to them. + +```bash +cat > x.txt < y1.txt < y2.txt < + +Blank wx0 display +*Figure: The initialization of display monitor wx0* + + + +All subsequently displayed data will be rendered on monitor `wx0`. + +```bash +g.region raster=elevation -p +d.rast map=elevation +``` + +
+ + +*Figure: The display wx0 showing an elevation raster map* + +
+ +### CAIRO file renderer monitor + +A CAIRO monitor can be started (and selected) by + +```bash +d.mon start=cairo output=out.pdf +``` + +From this moment on all displayed data will be rendered into file +`output.pdf`. + +### List running monitors + +To list the currently running monitors, use + +```bash +d.mon -l + +List of running monitors: +wx0 +cairo +``` + +### Show currently selected monitor + +To identify the currently selected monitor, use + +```bash +d.mon -p + +cairo +``` + +### Switching between monitors + +To switch back to interactive display mode, here to an earlier started +and still running wxGUI monitor, use + +```bash +d.mon select=wx0 +``` + +### Stopping a monitor + +To close the wxGUI monitor, run + +```bash +d.mon stop=wx0 +``` + +## SEE ALSO + +*[d.erase](d.erase.md), [d.redraw](d.redraw.md), [d.rast](d.rast.md), +[d.vect](d.vect.md), [d.frame](d.frame.md)* + +See also [list of variables for +rendering](variables.md#list-of-selected-grass-environment-variables-for-rendering), +[display drivers](displaydrivers.md) + +## AUTHOR + +Martin Landa, OSGeoREL, Czech Technical University in Prague, Czech +Republic diff --git a/display/d.northarrow/d.northarrow.md b/display/d.northarrow/d.northarrow.md new file mode 100644 index 00000000000..a9a1ab4a577 --- /dev/null +++ b/display/d.northarrow/d.northarrow.md @@ -0,0 +1,37 @@ +## DESCRIPTION + +*d.northarrow* displays a north arrow symbol at the given screen +coordinates. If no coordinates are given it will draw the north arrow in +the bottom right of the display. It can draw the north arrow in a number +of styles (see the [wiki +page](https://grasswiki.osgeo.org/wiki/Cartography#Display_monitors) for +details). With certain styles of north arrow label 'N' is displayed by +default, and can be changed with option **label**, for example for +different languages. The label can be hidden with **-t** flag. + +North arrow can be rotated, for example to align with true north, not +grid north. The angle in degrees counter-clockwise (or radians with +**-r** flag) can be specified with option **rotation**. Label is rotated +together with the arrow, unless flag **-w** is specified. + +## EXAMPLES + +Display a north arrow symbol as a basic compas with label NORTH, rotated +by 8 degrees with label, with black line and gray fill: + +```bash +d.mon wx0 +d.northarrow style=basic_compas rotation=8 label=NORTH -w color=black fill_color=gray +d.mon -r +``` + +## SEE ALSO + +*[d.barscale](d.barscale.md), [d.graph](d.graph.md), +[d.grid](d.grid.md), [d.legend](d.legend.md)* + +## AUTHORS + +Hamish Bowman, *Department of Geology, University of Otago, New +Zealand* +Improvements as part of GSoC 2016 by Adam Laza, *CTU in Prague* diff --git a/display/d.path/d.path.md b/display/d.path/d.path.md new file mode 100644 index 00000000000..0e851739054 --- /dev/null +++ b/display/d.path/d.path.md @@ -0,0 +1,47 @@ +## DESCRIPTION + +*d.path* enables shortest path vector networking. Costs may be either +line lengths, or attributes saved in a database table. Supported are +cost assignments for both arcs and nodes, and also different in both +directions of a vector line. For areas cost will be calculated along +boundary lines. + +## NOTE + +The user needs to display a vector map before using d.path. If no +graphics monitor is open, a file `map.png` is generated in the current +directory. + +The 'from' and 'to' points are entered by mouse into the map displayed +in the GRASS monitor, or if the **coordinates** option is used they can +be specified non-interactively. The actions bound to the mouse buttons +are described in the terminal window when running the command. + +To calculate shortest path non-interactively and save the path to a new +vector map, use the *v.net.path* module. + +## EXAMPLES + +Interactive shortest path routing on road network (North Carolina sample +dataset): + +```bash +g.region vector=roadsmajor -p +d.vect roadsmajor +d.path roadsmajor coordinates=668646.15,224447.16,668348.83,235894.02 +``` + +Non-interactive shortest path routing on road network (North Carolina +sample dataset): + +```bash +d.path -b roadsmajor coordinates=668646.15,224447.16,668348.83,235894.02 +``` + +## SEE ALSO + +*[v.net.path](v.net.path.md)* + +## AUTHOR + +Radim Blazek, ITC-Irst, Trento, Italy diff --git a/display/d.profile/d.profile.md b/display/d.profile/d.profile.md new file mode 100644 index 00000000000..10fa79eed27 --- /dev/null +++ b/display/d.profile/d.profile.md @@ -0,0 +1,14 @@ +## DESCRIPTION + +*d.profile* displays the profile for a specified transect. + +## SEE ALSO + +*[d.where](d.where.md), [r.profile](r.profile.md), +[r.transect](r.transect.md), [wxGUI profile tool](wxGUI.md)* + +## AUTHOR + +Glynn Clements This program has been completely re-written for 7.0. It +bears no relation to the interactive d.profile module in previous +versions. diff --git a/display/d.rast.arrow/d.rast.arrow.md b/display/d.rast.arrow/d.rast.arrow.md new file mode 100644 index 00000000000..ac2d06beccc --- /dev/null +++ b/display/d.rast.arrow/d.rast.arrow.md @@ -0,0 +1,103 @@ +## DESCRIPTION + +*d.rast.arrow* is designed to help users better visualize surface water +flow direction, as indicated in an aspect raster map layer. There are +two ways to specify the aspect layer the program is to use. The first is +to display the aspect map layer on the graphics monitor before running +*d.rast.arrow*. The second method involves setting the *map* parameter +to the name of the desired aspect map. This allows the arrows to be +drawn over any other maps already displayed on the graphics monitor. + +*d.rast.arrow* will draw an arrow over each displayed cell to indicate +in which direction the cell slopes. If the aspect layer has a category +value denoting locations of "unknown" aspect, *d.rast.arrow* draws a +question mark over the displayed cells of that category. Cells +containing null data will be marked with an "X". You can disable drawing +of null data and unknown aspect values by setting its color to "`none`". + +When specifying the *magnitude_map* option, arrow lengths denoting +magnitude will be extracted from the cell values of the specified map. +In this case the tail of the arrow will be centered on the source cell. +You may adjust the overall scale using the *scale* option. +*d.rast.arrow* will ignore NULL and negative magnitudes, and will warn +you if the debug level is set at 5 or higher. Be aware. If your +application uses negative values for magnitude, you can use +*[r.mapcalc](r.mapcalc.md)* to prepare the magnitude map to suit your +needs (absolute value, inverted direction and so on). + +## NOTES + +By default, arrows are drawn at the size of a cell and cannot be seen if +the raster map is relatively close in scale. You can use the *skip* +option to draw arrows every n-th cell in both directions if you are +working with relatively high resolutions. It may be useful to disable +the grid in this case, which is accomplished by setting its color to +"`none`". + +For GRASS and Compass type aspect maps, the cell values of the aspect +map will determine the corresponding direction in 360 degrees. ANSWERS +type aspect maps will be plotted in multiples of 15 degrees +counterclockwise from east, and AGNPS and Drainage type aspect maps will +be displayed in D8 representation, i.e. the eight multiples of 45 +degrees. Cell values are 1 to 8 clockwise from north for AGNPS and 1 to +8 counterclockwise from north east for Drainage. See +*[r.watershed](r.watershed.md)* for more details about the Drainage +aspect. Terraflow (same as ArcGIS) type aspect map will use a +power-of-two encoding clockwise from 1 for east to 128 for north east. +See *[r.terraflow](r.terraflow.md)* for more details about the Terraflow +encoding. + +GRASS aspect maps are measured using Cartesian conventions, i.e. in +degrees counterclockwise from east. e.g.: + +```bash +90 North +180 West +270 South +0,360 East +``` + +They can be created from a raster elevation map with +*[r.slope.aspect](r.slope.aspect.md)*. + +Compass type aspect maps are measured in degrees clockwise from north. + +This module uses oceanographic conventions, i.e. arrows point downslope +or direction "to", as opposed to atmospheric conventions (direction +"from"). + +## EXAMPLE + +Convert U,V velocity component maps into magnitude,direction maps for +use with *d.rast.arrow*: + +```bash +r.mapcalc "magnitude = sqrt(U_map^2 + V_map^2)" +r.mapcalc "direction = atan(U_map, V_map)" +d.rast.arrow map=direction type=grass magnitude_map=magnitude skip=3 grid=none +``` + +![](d_rast_arrow_wind.png) +*Sea wind speed (magnitude) and direction shown in the Tasmanian Sea* + +## SEE ALSO + +*[d.frame](d.frame.md), [d.rast](d.rast.md), +[d.rast.edit](d.rast.edit.md), [d.rast.num](d.rast.num.md), +[g.region](g.region.md), [r.slope.aspect](r.slope.aspect.md), +[r.watershed](r.watershed.md), [r.terraflow](r.terraflow.md)* + +## AUTHORS + +Original author +Chris Rewerts +*Agricultural Engineering, +Purdue University* + +Magnitude and 360 arrow code +Hamish Bowman +*Department of Marine Science, +University of Otago, New Zealand* + +Align grids with raster cells and Drainage aspect type +Huidae Cho diff --git a/display/d.rast.num/d.rast.num.md b/display/d.rast.num/d.rast.num.md new file mode 100644 index 00000000000..ba2a2f9b2dd --- /dev/null +++ b/display/d.rast.num/d.rast.num.md @@ -0,0 +1,52 @@ +## DESCRIPTION + +*d.rast.num* overlays cell category values onto a raster map layer +displayed on the user's graphics monitor. Category values will be +displayed in the text color given and scaled to fit within a single +cell. A grid outlining each map cell will also be overlain in a +user-specified color, unless it has been set to "none". + +If no grid color is given the default will be used. If no map layer is +specified, the program will use whatever raster map layer is currently +displayed in the active frame on the graphics monitor. + +If the **-f** flag is given the displayed number will take on the color +of the base map in that cell. + +## NOTES + +The user is advised to set the current region to a relatively small area +(i.e., less than 100 rows by 100 columns); otherwise, the individual +cells being displayed will be small and the category value associated +with each will be difficult to see. No data cells are indicated with +"Null". + +## EXAMPLE + +Distance from the streams network (North Carolina sample dataset): + +```bash +g.region raster=streams_derived -p +r.grow.distance input=streams_derived distance=dist_from_streams +d.rast.num dist_from_streams -a +``` + +
+ + +*Euclidean distance from the streams network in meters (detail, numbers +shown with d.rast.num)* + +
+ +## SEE ALSO + +*[d.frame](d.frame.md), [d.grid](d.grid.md), [d.rast](d.rast.md), +[d.rast.arrow](d.rast.arrow.md), [d.rast.edit](d.rast.edit.md), +[g.region](g.region.md), [r.slope.aspect](r.slope.aspect.md)* + +## AUTHORS + +Raghavan Srinivasan, and Chris Rewerts, +Agricultural Engineering, Purdue University diff --git a/display/d.rast/d.rast.md b/display/d.rast/d.rast.md new file mode 100644 index 00000000000..f13ce21adad --- /dev/null +++ b/display/d.rast/d.rast.md @@ -0,0 +1,60 @@ +## DESCRIPTION + +*d.rast* displays the specified raster map in the active display frame +on the graphics monitor. + +## EXAMPLE + +Display raster map "elevation": + +```bash +d.rast map=elevation +``` + +
+ + +*Figure: elevation raster map visualization* + +
+ +Display raster map "elevation" but only the raster cells with values +between 75 and 80 meters: + +```bash +d.rast map=elevation values=75-80 +``` + +
+ + +*Figure: elevation raster map showing values between 75 and 80 meters* + +
+ +Display raster map "landuse96_28m" but only categories 1 and 2: + +```bash +d.rast landuse96_28m values=1,2 +``` + +
+ +d.rast landuse +*Figure: landuse raster map showing categories 1 and 2* + +
+ +## SEE ALSO + +*[d.rast.arrow](d.rast.arrow.md), [d.rast.num](d.rast.num.md), +[d.rast.leg](d.rast.leg.md), [d.legend](d.legend.md), [d.mon](d.mon.md), +[d.erase](d.erase.md), [d.vect](d.vect.md)* + +*[wxGUI](wxGUI.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.redraw/d.redraw.md b/display/d.redraw/d.redraw.md new file mode 100644 index 00000000000..74e39cc6da7 --- /dev/null +++ b/display/d.redraw/d.redraw.md @@ -0,0 +1,14 @@ +## DESCRIPTION + +*d.redraw* redraws the content of the currently selected monitor. The +active monitor can be selected with *d.mon*. + +## SEE ALSO + +*[d.erase](d.erase.md), [d.rast](d.rast.md), [d.vect](d.vect.md), +[d.mon](d.mon.md)* + +## AUTHOR + +Huidae Cho, New Mexico State University +Based on the *d.redraw* script by Martin Landa, Czech Republic diff --git a/display/d.rgb/d.rgb.md b/display/d.rgb/d.rgb.md new file mode 100644 index 00000000000..cbf1f70dfdd --- /dev/null +++ b/display/d.rgb/d.rgb.md @@ -0,0 +1,68 @@ +## DESCRIPTION + +*d.rgb* displays three user-specified raster maps as red, green, and +blue overlays in the active graphics frame. + +*RGB* stands for **red**, **green**, and **blue**. *d.rgb* visually +combines three raster maps to form a color image. For each map, the +corresponding component from the layer's color table is used (e.g. for +the red layer, the red component is used, and so on). In general, the +input raster maps should use a grey-scale color table. + +## NOTES + +*d.rgb* does not attempt to quantize the combined image into a fixed +number of colors. Nor does it have an option to generate a composite +layer (see *r.composite* for that). The image and raster maps will not +display properly if the graphics device does not have a reasonable +sampling of the RGB color-space. + +If color quality of satellite image color composites seems to appear +poor, run *[i.colors.enhance](i.colors.enhance.md)* on the selected +satellite channels. + +An alternative is the assignment of grey color tables to each band with +*[r.colors](r.colors.md)*: + +```bash +r.info -r image.1 + +min=0 +max=255 + +r.colors map=image.1 color=grey + +r.colors map=image.2 rast=image.1 +r.colors map=image.3 rast=image.1 +``` + +To write out the color composite to a combined R/G/B raster maps, use +*[r.composite](r.composite.md)*. + +## EXAMPLE + +Visual color composite of a LANDSAT scene (North Carolina sample +dataset): + +```bash +g.region raster=lsat7_2002_10 -p +d.rgb blue=lsat7_2002_10 green=lsat7_2002_20 red=lsat7_2002_30 +``` + +
+ +d.rgb example +*Figure: Visual color composite of a LANDSAT scene (North Carolina +sample dataset)* + +
+ +## SEE ALSO + +*[d.colortable](d.colortable.md), [d.his](d.his.md), +[r.blend](r.blend.md), [r.mapcalc](r.mapcalc.md), +[r.colors](r.colors.md), [r.composite](r.composite.md)* + +## AUTHOR + +Glynn Clements diff --git a/display/d.rhumbline/d.rhumbline.md b/display/d.rhumbline/d.rhumbline.md new file mode 100644 index 00000000000..1ca907c1566 --- /dev/null +++ b/display/d.rhumbline/d.rhumbline.md @@ -0,0 +1,45 @@ +## DESCRIPTION + +A rhumbline (loxodrome) is a line following a constant angle of the +compass (i.e., a line of constant direction). It crosses all meridians +at the same angle, i.e. a path of constant bearing. *d.rhumbline* +displays the rhumbline joining any two user-specified points in the +active frame on the user's graphics monitor. The named coordinate +locations must fall within the boundaries of the user's current +geographic region. + +The user has to specify the starting and ending longitude/latitude +coordinates of the rhumbline and (optionally) the color in which the +rhumbline will be displayed; in this case, the program will run +non-interactively. + +## EXAMPLE + +A geodesic line if shown over the political map of the world +(demolocation dataset): + +```bash +g.region vector=country_boundaries -p +d.mon wx0 +d.vect country_boundaries type=area +d.rhumbline coordinates=55:58W,33:18S,26:43E,60:37N \ + line_color=yellow +# show additionally 10 degree grid +d.grid 10 +``` + + +*Rhumbline (loxodrome)* + +## NOTES + +This program works only with longitude/latitude coordinate system. + +## SEE ALSO + +*[d.geodesic](d.geodesic.md), [d.grid](d.grid.md), +[m.measure](m.measure.md)* + +## AUTHOR + +Michael Shapiro, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.text/d.text.md b/display/d.text/d.text.md new file mode 100644 index 00000000000..d720f53a22b --- /dev/null +++ b/display/d.text/d.text.md @@ -0,0 +1,79 @@ +## DESCRIPTION + +*d.text* draws text in the active display frame on the graphics monitor. +Text can be provided through standard input or redirected from a file +(using the UNIX redirection mechanism). In addition to the options +provided on the command line, colors, text size, font type, rotation +angle, and boldness can be adjusted with commands in the standard input +(i.e., if the user invokes *d.text* without options on the command line, +and then assigns values to these options on lines within the standard +input). + +### Commands + +**.C** *color* +(where *color* is one of the available colors) causes text appearing on +subsequent lines to be drawn in that color. + +**.G** *color* +(where *color* is one of the available colors) causes the background of +text appearing on subsequent lines to be drawn in that color. + +**.S** *size* +(where *size* is a percentage within the range 0 to 100) adjusts text +size. Note that a size of 10 would allow 10 lines to be drawn in the +active display frame, 5 would allow the drawing of 20 lines, and 50 +would allow the drawing of 2 lines. + +**.F** *font* +(where *font* is one of the fonts known by the GRASS program +*[d.font](d.font.md)*) manipulates the font type. Available fonts are +listed in the GRASS manual entry for *[d.font](d.font.md)*. The default +font type used (if unspecified by the user) is *romans*. + +**.R** *rotation* +(where *rotation* is an angle in degrees, counter-clockwise) to rotate +the text. + +**.B 1** +stipulates that following text be printed in **bold**. This command +means *bold on*. + +**.B 0** +turns *bold off* of all text appearing on lines beneath it. (*Bold off* +is used by default, if unspecified by the user.) + +## EXAMPLE + +The following command will print the short phrase "This is a test of +d.text" in the active display frame using the color yellow, in bold, and +using 4/100'ths (4%) of the active frame's vertical space per line: + +```bash +d.text text="This is a test of d.text" color=yellow bgcolor=gray size=4 +``` + +
+ + +*Displayed Text* + +
+ +## NOTES + +Note that the GRASS command *[d.title](d.title.md)* creates map TITLEs +in a format suitable for input to *d.text*. + +*d.text* needs escape sequences that can be used within lines to change +colors, boldness, and perhaps size. + +## SEE ALSO + +*[d.font](d.font.md), [d.title](d.title.md), [d.labels](d.labels.md)* + +## AUTHORS + +James Westervelt, U.S. Army Construction Engineering Research Laboratory + +Updates by Huidae Cho diff --git a/display/d.title/d.title.md b/display/d.title/d.title.md new file mode 100644 index 00000000000..9d469837108 --- /dev/null +++ b/display/d.title/d.title.md @@ -0,0 +1,48 @@ +## DESCRIPTION + +*d.title* generates to standard output a string which can be used by +*[d.text](d.text.md)* to draw a TITLE for the raster map layer *name* in +the active display frame on the graphics monitor. Output created by +*d.title* can be redirected into a file, or piped directly into +*[d.text](d.text.md)* to display the map TITLE created by *d.title*. The +map TITLE created will include the map layer's name, TITLE, MAPSET, +LOCATION_NAME, geographic region boundary coordinates, and cell +resolution. If the **-d** draw flag is used, then *d.title* will call +*d.text* for you and the title will be automatically rendered to the +display. + +## NOTES + +The text created with *[d.text](d.text.md)* will not necessarily fit +within the active display frame on the graphics monitor; the user should +choose a text size appropriate to this frame. + +## EXAMPLES + +For example, a user wishing to create a suitable TITLE for the +Spearfish, SD *soils* map layer and to display this TITLE in the active +display frame on the graphics monitor might type the following: + +```bash +d.title map=soils color=red size=5 > TITLE.file +d.text < TITLE.file +``` + +Alternately, the user might pipe *d.title* output directly into +*[d.text](d.text.md):* + +```bash +d.title map=soils color=red size=5 | d.text +``` + +A file created by *d.title* can be displayed with *[d.text](d.text.md)*. +Information contained in this file takes precedence over the *color* and +*size* parameters for *[d.text](d.text.md)*. + +## SEE ALSO + +*[d.font](d.font.md), [d.text](d.text.md)* + +## AUTHOR + +James Westervelt, U.S. Army Construction Engineering Research Laboratory diff --git a/display/d.vect.chart/d.vect.chart.md b/display/d.vect.chart/d.vect.chart.md new file mode 100644 index 00000000000..4cf1967c09f --- /dev/null +++ b/display/d.vect.chart/d.vect.chart.md @@ -0,0 +1,84 @@ +## DESCRIPTION + +*d.vect.chart* displays charts for GRASS vector data in the active frame +on the graphics monitor. + +## NOTES + +The charts are positioned as follows: + +- vector points: on point position, +- vector lines: on line centers, +- vector areas: on area centroids. + +Bar charts are placed with their lower edge starting from the +y-coordinate of the feature being symbolized, and centered with respect +to the x-coordinate. The **-c** flag can be used to center the bar chart +in both x and y directions. + +The 'sizecol' parameter is proportionate to the radius. + +The optional **max_ref** parameter accepts a list of values that +represent the maximum value for each column listed in the values for the +parameter **columns**. These values are used to create a framed bar plot +if **chart_type** is *bar* (See Example 2). + +## EXAMPLES + +### Example 1 + +Pie-charts of monthly winter precipitation (North Carolina sample +dataset): + +```bash +g.region vector=nc_state -p +d.vect nc_state +d.vect.chart precip_30ynormals chart_type=pie columns=nov,dec,jan,feb -l + +# show pie chart as 3D +d.erase +d.vect nc_state +d.vect.chart precip_30ynormals chart_type=pie columns=nov,dec,jan,feb -l -3 +``` + +![d.vect.chart 2D pie chart](d_vect_chart_pie_2d.png) +2D pie-chart of monthly winter precipitation in North Carolina + +![d.vect.chart 3D pie chart](d_vect_chart_pie_3d.png) +3D pie-chart of monthly winter precipitation in North Carolina + +### Example 2 + +Bar-chart of different census map values: + +```bash +d.vect.chart map=vectmap columns=cens51,cens61,cens71,cens81 chart_type=bar +``` + +### Example 3 + +Creation of framed bar charts of an erodibiliy index from the Spearfish +sample dataset: + +```bash +g.region raster=erode.index -p +r.to.vect -s input=erode.index output=erode_index type=area +v.extract input=erode_index output=erode_index_ctrds type=centroid +d.rast aspect +d.vect.chart map=erode_index_ctrds chart_type=bar columns=cat \ + size=10 max_ref=12 scale=0.05 colors=yellow +d.vect erode_index_ctrds icon=basic/circle fcol=black col=black size=5 +``` + +![d.vect.chart example](d.vect.chart_example.jpg) +Bar charts of an erodibiliy index (spatial subset) + +## SEE ALSO + +*[d.erase](d.erase.md), [d.vect](d.vect.md), +[d.vect.thematic](d.vect.thematic.md), [d.what.vect](d.what.vect.md), +[d.rast](d.rast.md)* + +## AUTHOR + +Radim Blazek, ITC-Irst, Trento, Italy diff --git a/display/d.vect.thematic/d.vect.thematic.md b/display/d.vect.thematic/d.vect.thematic.md new file mode 100644 index 00000000000..a22d95a9dcc --- /dev/null +++ b/display/d.vect.thematic/d.vect.thematic.md @@ -0,0 +1,95 @@ +## DESCRIPTION + +*d.vect.thematic* draws thematic choropleth vector maps based on an +attribute column or an expression involving several columns. It takes a +list of class **breaks** (excluding the minimum and maximum values) and +a list of **colors** to apply to the classes (has to be the number of +class breaks + 1). + +Instead of a list of class breaks, the user can also chose a +classification **algorithm** and a number of classes (**nbclasses**). +See the *[v.class](v.class.md)* for more information on these different +algorithms. + +## NOTES + +The **-l** flag instructs the module to print legend information in +vector legend format as described in *[d.legend.vect](d.legend.vect.md)* +to standard output for further use in graphical software. When combined +with the verbose flag, the legend information will be extended with some +additional statistical information. If the **-n** flag is set, the +module will only print the legend information without drawing the map. + +Option **legendfile**, is deprecated, instead use the GRASS_LEGEND_FILE +environmental variable (see *[d.legend.vect](d.legend.vect.md)*) to save +legend into a file. Flag **-e** is deprecated, instead use verbose flag. + +## EXAMPLES + +### Thematic map with classes + +```bash +d.vect.thematic -l map=communes3 column=pop \ + breaks=111393.250000,222785.500000,334177.750000 \ + colors="255:0:0,0:255:0,0:0:255,0,0,0" +``` + +### Thematic map with calculated class breaks + +The following example uses a calculated attribute (`density = pop/area`) +and the standard deviation algorithm to calculate class breaks for 5 +classes: + +```bash +d.vect.thematic -l map=communes2 column=pop/area algorithm=std \ + nbclasses=5 colors="0:0:255,50:100:255,255:100:50,255:0:0,156:0:0" +``` + +### Thematic map with legend + +Example for the North Carolina sample dataset, colorizing basin polygons +by average elevation and displaying school capacity: + +```bash +# create watersheds from elevation map +g.region raster=elevation +r.watershed elevation=elevation threshold=10000 basin=basins_10k + +# convert raster to vector +r.to.vect input=basins_10k output=basins_10k type=area column=basin_num + +# upload raster statistics to each polygon in vector map +v.rast.stats map=basins_10k raster=elevation column_prefix=elev + +# open a graphical display +d.mon wx0 + +# draw thematic polygons and specify legend title +d.vect.thematic map=basins_10k column=elev_average algorithm=int \ + nclasses=5 colors=0:195:176,39:255:0,251:253:0,242:127:11,193:126:60 \ + legend_title="Average elevation (m)" + +# draw thematic points and specify legend title +d.vect.thematic map=schools_wake@PERMANENT column=CORECAPACI algorithm=std \ + nclasses=3 colors=149:203:255,45:143:240,0:81:161 icon=basic/circle size=15 \ + legend_title="School capacity" + +# and finally draw legend +d.legend.vect -b at=2,80 font=Sans symbol_size=25 +``` + +[](d_vect_thematic.png) +*Thematic map of average elevation and school capacity* + +## SEE ALSO + +*[v.class](v.class.md), [d.legend.vect](d.legend.vect.md), +[d.vect](d.vect.md), [d.graph](d.graph.md), [v.univar](v.univar.md)* + +Check also Python module from AddOns: +*[d.vect.thematic2](https://grass.osgeo.org/grass8/manuals/addons/d.vect.thematic2.html)* + +## AUTHOR + +Moritz Lennert diff --git a/display/d.vect/d.vect.md b/display/d.vect/d.vect.md new file mode 100644 index 00000000000..07305a8b828 --- /dev/null +++ b/display/d.vect/d.vect.md @@ -0,0 +1,133 @@ +## DESCRIPTION + +*d.vect* displays vector maps in the active frame on the graphics +monitor. + +## NOTES + +*d.vect* can simply be used typing `d.vect map=vector_map`. There are a +large variety of optional parameters which allow the user to specify +vector type, colors, data fields, SQL queries, label size and +justification, etc. + +When *d.vect* is used with **where** parameter on MS Windows Command +Prompt, it is important to use `ˆ` carret symbol for escaping special +characters `< > ( ) & | , ; "`. + +```bash +d.vect map=vector_map where="cat ˆ> 10 AND cat ˆ< 20" +``` + +By default *d.vect* areas are filled with **fill_color** and outlined +with **color**. Area outlines can be suppressed with + +```bash +d.vect map=vector_map color=none +``` + +and areas can be made transparent with + +```bash +d.vect map=vector_map fill_color=none +``` + +In order to display attributes in the map, **attribute_column** must be +specified. + +Feature colors may be specified by *[v.colors](v.colors.md)* in a form +of color table or in an attribute table column containing `RRR:GGG:BBB` +values. + +A table for a vector map might look like this: + +```bash +db.select sql="select * from testisola" +cat|label|GRASSRGB +0|no data|255:255:255 +90|FRASSILONGO|23:245:67 +104|LEVICO|23:145:67 +139|PERGINE VALSUGANA|223:45:237 +168|SANT'ORSOLA|223:45:67 +190|TENNA|123:45:67 +``` + +To add the GRASSRGB color column, use +*[v.db.addcolumn](v.db.addcolumn.md)*: + +```bash +v.db.addcolumn map=testisola columns="GRASSRGB varchar(11)" +``` + +To add/change a color, use *[v.db.update](v.db.update.md)*: + +```bash +v.db.update map=testisola column=GRASSRGB value="123:45:237" where="cat=139" +``` + +A much simpler method of color coding is by using the **-c** flag which +displays vector elements of like category number with a random color. + +This module can use FreeType/TrueType fonts if they have already been +selected with *[d.font](d.font.md)*. + +Parameter **width** is set by default to '0'. XDRIVER specifies the +precise behaviour for non-zero line width, but drivers have some freedom +as to how zero-width lines are handled, so they can use the hardware's +"thin line" drawing primitive, if it has one. A width of zero can +potentially result in significantly faster operation. On drivers where +there is no such thing as a "thin" line, the driver will use a sensible +default (which might not be the same as '1'). + +## EXAMPLES + +Spearfish examples: + +```bash +# display roads with category numbers: +d.vect map=roads display=shape,cat label_color=green + +# display randomly colorized soils map with attributes +d.vect -c map=soils attribute_column=label + +# display randomly colorized selected vectors from soils map +d.vect -c map=soils where="label='VBF'" display=shape attribute_column=label +``` + +3D points, 3D lines and 3D polygons colorized according to z height (for +3D lines and polygons a z height is computed by a midpoint of line/area +bounding box): + +```bash +g.region raster=elevation.10m +r.random input=elevation.10m n=5000 vector=random3d -d +d.mon start=x0 +# display as black points +d.vect map=random3d +# display 3D points colorized according to z height +d.vect map=random3d zcolor=gyr + +# 3D contour lines +r.contour input=elevation.10m output=contour20m step=20 +d.vect map=contour20m zcolor=gyr + +# generate 3D triangles +v.delaunay input=random3d output=random3d_del +# display 3D polygons colorized according to z height +d.vect map=random3d_del type=area zcolor=gyr +``` + +## SEE ALSO + +*[v.colors](v.colors.md), [d.erase](d.erase.md), [d.rast](d.rast.md), +[v.colors](v.colors.md), [v.db.addcolumn](v.db.addcolumn.md), +[v.db.update](v.db.update.md)* + +*[GRASS SQL interface](sql.md)* + +## AUTHORS + +CERL +Radim Blazek, ITC-Irst, Trento, Italy +Support for color tables by Martin Landa, Czech Technical University in +Prague (8/2011) +and many other GRASS developers diff --git a/display/d.where/d.where.md b/display/d.where/d.where.md new file mode 100644 index 00000000000..43b169492d2 --- /dev/null +++ b/display/d.where/d.where.md @@ -0,0 +1,58 @@ +## DESCRIPTION + +*d.where* is an *interactive* program that allows the user, using the +pointing device (mouse), to identify the geographic coordinates +associated with point locations within the current geographic region in +the active display frame on the graphics monitor. + +Each mouse click will output the easting and northing of the point +currently located beneath the mouse pointer. A mouse-button menu is +presented so the user knows which mouse buttons to use. The output is +always printed to the terminal screen; if the output is redirected into +a file, it will be written to the file as well. + +Mouse buttons: + +```bash + Left: where am i + Middle: draw to/from here + Right: quit this +``` + +The left mouse button prints the coordinates at the selected point, the +middle mouse button allows you to query two points (they are connected +by a line for convenience). Use the right mouse button to exit the +module. + +## NOTES + +This program uses the current geographic region setting and active +frame. It is not necessary, although useful, to have displayed a map in +the current frame before running *d.where*. The **-d** flag allows the +user to optionally output latitude/longitude coordinates pair(s) in +decimal degree rather than DD:MM:SS format. The **-w** flag is only +valid if a datum is defined for the current project's coordinate +reference system. If the **-f** flag is given the x,y frame coordinates +of the active display monitor will be returned (as a percentage, 0,0 is +bottom left). + +## EXAMPLE + +Query position in map (North Carolina sample dataset): + +```bash +d.rast elevation +d.where +``` + +## SEE ALSO + +*[d.what.rast](d.what.rast.md), [d.what.vect](d.what.vect.md), +[g.region](g.region.md), [v.what.rast](v.what.rast.md), +[v.what.vect](v.what.vect.md)* + +## AUTHORS + +James Westervelt, +Michael Shapiro, +U.S. Army Construction Engineering Research Laboratory diff --git a/display/displaydrivers.md b/display/displaydrivers.md new file mode 100644 index 00000000000..caa93d97b5a --- /dev/null +++ b/display/displaydrivers.md @@ -0,0 +1,63 @@ +The current command line rendering mechanism is direct rendering into a +file. The driver is selected by setting the `GRASS_RENDER_IMMEDIATE` +variable or by running *[d.mon](d.mon.md)* module. + +**List of available display drivers:** + +- [Cairo driver](cairodriver.md) +- [PNG driver](pngdriver.md) +- [PS driver (Postscript)](psdriver.md) +- [HTMLMAP driver](htmldriver.md) + +## NOTES + +### GRASS_RENDER_COMMAND + +If environmental variable GRASS_RENDER_COMMAND is defined, rendering is +redirected by display library to the given external command defined by +this variable. Currently only Python scrips are supported. + +Lets start with simple example of Python script called *render.py*: + +```bash +#!/usr/bin/env python3 + +import os +import sys + +import grass.script as gs +from grass.script import task as gtask + +os.environ['GRASS_RENDER_IMMEDIATE'] = 'default' +os.environ['GRASS_RENDER_FILE'] = 'output.png' + +cmd, dcmd = gtask.cmdstring_to_tuple(sys.argv[1]) + +gs.run_command('d.text', text="Test of GRASS_RENDER_COMMAND redirection") + +os.environ['GRASS_RENDER_FILE_READ'] = 'TRUE' +gs.run_command(cmd, **dcmd) +``` + +After defining GRASS_RENDER_COMMAND variable (example for Bash): + +```bash +export GRASS_RENDER_COMMAND=render.py +``` + +Display GRASS modules like *[d.rast](d.rast.md)* or +*[d.vect](d.vect.md)* will be executed by *render.py* program. For +example the command + +```bash +d.vect roadsmajor +``` + +produces output PNG file *output.png* which will contain rendered +features from vector map *roadsmajor* and sample text *"Test of +GRASS_RENDER_COMMAND redirection"*. + +## SEE ALSO + +*[d.mon](d.mon.md), +[variables](variables.md#list-of-selected-grass-environment-variables-for-rendering)* diff --git a/doc/grass_database.md b/doc/grass_database.md new file mode 100644 index 00000000000..f729e9c76f7 --- /dev/null +++ b/doc/grass_database.md @@ -0,0 +1,206 @@ +A GRASS GIS Database is simply a set of directories and files with +certain structure which GRASS GIS works efficiently with. Project is a +directory with data related to one geographic location or a project. All +data within one project has the same coordinate reference system. A +project contains mapsets and each mapset contains data related to a +specific task, user or a smaller project. Within each project, a +mandatory PERMANENT mapset exists which can contain commonly used data +within one GRASS project such as base maps. The PERMANENT mapset also +contains metadata related to the project such as the coordinate +reference system. When GRASS GIS is started it connects to a database, +project and mapset specified by the user. + +![example: nc_spm - highway - elevation](grass_database.png) +*Fig. 1: GRASS GIS Database structure as visible to the user* + +### GRASS GIS Database + +All data for GRASS GIS must be in GRASS GIS Database which is a +directory (visible on the disk) containing subdirectories which are +GRASS projects. User can have one or more of Databases on the disk. +Typically users have one directory called `grassdata` in their home +directory. In multi-user environment users often have a `grassdata` +directory mounted as a network directory (network file system). For +teams, a centralized GRASS DATABASE would be defined in a shared network +file system (e.g. NFS). + +GRASS GIS Databases can be safely copied or moved as any other +directories. Don't be confused with (relational) databases which are +used in GRASS GIS to hold attribute data and might be part of the GRASS +GIS Database. From user point of view, GRASS GIS Database with all its +data in it is similar to, e.g. PostGIS, database, as it stores all +information inside in a specific format and is accessible by specific +tools. GRASS GIS Databases is in GRASS GIS often called GISDBASE or +DATABASE. + +### GRASS Projects + +A project is further organized into mapsets which are subdirectories of +the project directory. All data in one project have the same coordinate +reference system (projection, datum). Each project contains a mapset +called PERMANENT. Typically, a project contains all data related to one +real-world project or a geographic area (geographic location or region). +Alternatively, a project can simply contain data in a given coordinate +reference system. + +GRASS projects can be safely copied or moved as any other directories. +Compressed projects are usually what GRASS users exchange between each +other when they want to share a lot of data. For example, GRASS GIS +sample data are provided as projects. + +Note that a GRASS project used to be called *location* and this name has +not been completely removed from code and documentation yet. + +Users and programmers familiar with relational databases such as +PostgreSQL can view projects as individual databases inside a storage +area (the GRASS GIS Database). Mapsets in a project are like namespaces +or schemas inside a database. + +### GRASS Mapsets + +Mapsets contains the actual data, mostly geospatial data, referred to as +maps in GRASS GIS. Mapsets are a tool for organizing maps in a +transparent way as well as a tool for isolating different tasks to +prevent data loss. + +GRASS GIS is always connected to one particular mapset. GRASS GIS +modules can create, modify, change, or delete a data only in the current +mapset. By default, only the data from the current mapset and PERMANENT +mapset are visible. Using [*g.mapsets*](g.mapsets.md) module or in GUI +other mapsets can be made visible and seamlessly accessible. All data +are available for reading when mapset is specified explicitly, for +example to access map `streets` in mapset `new_highway` user can use +`streets@new_highway`. For maps which are in the current or PERMAENT +mapsets or mapsets sets as visible (accessible), there is no need to use +`@mapset` syntax. + +Mapsets are used to store maps related to one project, smaller project, +specific task, issue or subregions. In a multi-user environment, where +team members work together on a single project, individual mapsets +support simultaneous access of several users to the maps stored within +the same project. Besides access to their own mapset, each user can also +read maps in PERMANENT Mapsent and in other users' mapsets when set. +However, each user can modify or remove only the maps in his or her own +mapset. + +Besides the geospatial data, mapset holds additional data such as color +tables (managed e.g. by [*r.colors*](r.colors.md)) and the current +computational region's extent and resolution stored in a file called +`WIND` and managed by [*g.region*](g.region.md). + +Mapsets can be copied and moved as directories only when it is clear +that their coordinate reference systems (as reported by +[*g.proj*](g.proj.md)) match. In case of data coming with different +coordinate reference systems, it is recommended to use +[*r.proj*](r.proj.md) or [*v.proj*](v.proj.md) to reproject the data. +The files and directories should not be moved or modified directly, but +only using GRASS GIS tools. + +### The role of the PERMANENT Mapset + +When creating a new project, GRASS GIS automatically creates a special +mapset called PERMANENT where the core data for the project are stored. + +Since the maps in PERMANENT mapset are visible from all the other +mapsets, it can be used to store the base maps (base cartography), data +common to all projects or needed for different analyses done is separate +mapsets. + +In multi-user environment, data in the PERMANENT mapset can only be +added, modified or removed by the owner of the PERMANENT mapset; +however, they can be accessed, analyzed, and copied into their own +mapset by the other users. The PERMANENT mapset is useful for providing +general spatial data (e.g. an elevation model), accessible but +write-protected to all users who are working with the same GRASS project +as the database owner. To manipulate or add data to PERMANENT, the owner +can start GRASS GIS and choose the relevant project and the PERMANENT +mapset. + +The PERMANENT mapset also contains the `DEFAULT_WIND` file which holds +the default computational region's extent and resolution values for the +project (which all mapsets will inherit when they are created). Users +have the option of switching back to the default region at any time. + +### Importing, exporting and linking data + +GRASS GIS works only with data which are imported into a GRASS Database, +so all data needs to be imported, e.g. by [*r.in.gdal*](r.in.gdal.md) or +highly convenient [*r.import*](r.import.md), before the actual analysis. +Data in GRASS Datable can be exported using for example +[*r.in.gdal*](r.in.gdal.md) in case of raster maps. + +For cases when import is not desirable, an option to link external data +exists. The coordinate reference system of the linked data must match +the project's coordinate reference system otherwise the external data +cannot be linked. (Linking data in different projection is not allowed +as it would require on-the-fly reprojection which could cause +inconsistencies in the data. + +For example, module [*r.external*](r.external.md) links external raster +data, so that the data are accessible in GRASS Database as standard +raster maps. Similarly for newly created maps, +[*r.external.out*](r.external.out.md) setups a format and directory +where the actual data will be stored, however in GRASS Database the data +will be created as standard maps. + +### Starting GRASS GIS + +After launching GRASS GIS for the first time, the GUI opens in a default +project `world_latlong_wgs84`. From there a new project can be created. + +![GRASS GIS GUI after first start](grass_start.png) + +GRASS GIS can be also started with a given database, project and mapset +from the command line. For example, the following will start in a given +mapset with only command line interface: + +```bash +# Linux, Mac, *BSD, ...: +grass --text ~/grassdata/nc_spm_08_grass7/user1 + +# Windows +grass --text D:\grassdata\nc_spm_08_grass7\user1 +``` + +And the following will create the given project with coordinate +reference system given by the EPSG code and it will start the default +interface (GUI or command line): + +```bash +# Linux, Mac, *BSD, ...: +grass -c EPSG:5514:3 ~/grassdata/myproject + +# Windows +grass -c EPSG:5514:3 D:\grassdata\myproject +``` + +See [*grass*](grass.md) command manual for more details. + +### Creating a New Project with the Project Wizard + +The [GUI](wxGUI.md) provides a graphical *Project Wizard* which lets you +easily create a new project for your own data. You will be guided +through a series of dialogues to browse and select predefined +projections or to define custom projections. + +The most convenient way of using the *Project Wizard* is creating new +project based on a georeferenced file, such as Shapefile or GeoTIFF, or +by selecting the corresponding EPSG code of the coordinate reference +system. In case of using georeferenced file, you are asked whether the +data itself should be imported into the new project. The default region +is then set to match imported map. + +If data were already imported, you can add them into the Layer Manager +now and display them. More data can be imported into the project, e.g. +using import options in the *File* menu in *Layer Manager* or +[*r.import*](r.import.md). + +## See also + +*[GRASS GIS Reference Manual](index.md) +[GRASS GIS startup program manual page](grass.md) +[Importing data on GRASS +Wiki](https://grasswiki.osgeo.org/wiki/Importing_data) +[r.import](r.import.md), [v.import](v.import.md), +[r.external](r.external.md), [v.external](v.external.md), +[r.proj](r.proj.md), [v.proj](v.proj.md),* diff --git a/doc/gui/wxpython/example/g.gui.example.md b/doc/gui/wxpython/example/g.gui.example.md new file mode 100644 index 00000000000..be5651ffbb1 --- /dev/null +++ b/doc/gui/wxpython/example/g.gui.example.md @@ -0,0 +1,36 @@ +## DESCRIPTION + +The purpose of the **Example Tool** is to make life easier for new wxGUI +developers. It can serve as a basic template when creating standalone +GRASS GUI-based application. Example tool can display one raster map a +show information about it. + +Following topics are covered: + +- creating standalone window +- adding toolbars, statusbar +- displaying raster map +- running GRASS modules from application +- creating dialog for element (raster, vector, ...) selection +- using temporary region +- access from main menu +- writing programmer documentation +- writing user documentation + +## NOTE + +See README to learn how to get Example Tool to work. + +### EXAMPLE TOOL TOOLBAR + +![](icons/layer-raster-add.png)  *Select raster layer* +Select raster layer and compute statistics related to this layer. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +## AUTHOR + +Anna Kratochvilova, [Czech Technical University in +Prague](https://www.cvut.cz), Czech Republic diff --git a/doc/projectionintro.md b/doc/projectionintro.md new file mode 100644 index 00000000000..7c2e2abf965 --- /dev/null +++ b/doc/projectionintro.md @@ -0,0 +1,77 @@ +### Projection management in general + +A GRASS project is referenced with a single projection and coordinate +system (or unreferenced as XY project). When creating a new project from +an existing raster or vector map using the tools available from the +startup screen or the map import commands, projection and coordinate +system are defined. To change the projection of maps, a new project has +to be created and the desired maps have to be reprojected into it from +the source project as explained below. + +### Reprojecting raster maps + +Rasters are reprojected using the raster projection tool +*[r.proj](r.proj.md)*. The tool is used in the target project to "pull" +a map from its source project. Both projects need to have a projection +defined, i.e., they cannot be XY (unprojected). + +### Raster map transformation + +To transform an unprojected map from a XY project into a projected +project (or another XY project), a forward transformation is performed. +The unreferenced map is geocoded within the XY project by defining four +corner points or by seeking several ground control points +([i.group](i.group.md), [i.target](i.target.md), +[g.gui.gcp](g.gui.gcp.md)) and then transformed into the target project +([i.rectify](i.rectify.md)). Polynomial transformation of 1st, 2nd and +3rd order are supported. + +A graphical user interface is provided by [wxGUI](wxGUI.md). + +To simply translate a raster map (without stretching or rotation), the +[r.region](r.region.md) command can be used. + +### Vector map projections + +Vectors are reprojected using the vector projection tool +*[v.proj](v.proj.md)*. The tool is used in the target project to "pull" +a map from its source project. Both projects need to have a projection +defined, i.e., they cannot be XY (unprojected). + +### Vector map transformation + +To transform an unprojected map (e.g. CAD map) into projected +coordinates, a forward transformation is performed. The unreferenced map +is imported into the project with projection and geocoded within this +project by defining four corner points or by seeking several ground +control points. These points are stored into an ASCII file and then +transformed within the same project ([v.transform](v.transform.md)). +Alternatively, [v.rectify](v.rectify.md) rectifies a vector by computing +a coordinate transformation for each object in the vector based on the +control points. + +A graphical user interface is provided by [wxGUI](wxGUI.md). + +### References + +- [ASPRS Grids and + Datum](https://www.asprs.org/asprs-publications/grids-and-datums) +- [Projections Transform List](http://geotiff.maptools.org/proj_list/) + (PROJ) +- [Coordinate operations](https://proj.org/operations/index.html) by + PROJ (projections, conversions, transformations, pipeline operator) +- [MapRef - The Collection of Map Projections and Reference Systems for + Europe](https://mapref.org) +- [Information and Service System for European Coordinate Reference + Systems - CRS](https://www.crs-geo.eu/) + +### See also + +- [Introduction into raster data processing](rasterintro.md) +- [Introduction into 3D raster data (voxel) + processing](raster3dintro.md) +- [Introduction into vector data processing](vectorintro.md) +- [Introduction into image processing](imageryintro.md) +- [Introduction into temporal data processing](temporalintro.md) +- [Database management](databaseintro.md) +- [Graphical User Interface](wxguiintro.md) diff --git a/doc/python/script/r.example.md b/doc/python/script/r.example.md new file mode 100644 index 00000000000..52bd8cae8b8 --- /dev/null +++ b/doc/python/script/r.example.md @@ -0,0 +1,29 @@ +## DESCRIPTION + +*r.example* selects values from raster above value of mean plus standard +deviation. See the source code for details. + +## NOTES + +Some more detailed notes go here. + +## EXAMPLE + +Computing the mean and standard deviation of the raster map "elevation" +(North Carolina sample dataset): + +```bash +g.region raster=elevation -p +r.example input=elevation output=elevation_mean_stddev +r.info elevation_mean_stddev +``` + +## SEE ALSO + +*[r.univar](r.univar.md), [r.mapcalc](r.mapcalc.md), +[v.example](v.example.md)* [GRASS Programmer's +Manual](https://grass.osgeo.org/programming8/) + +## AUTHOR + +GRASS Development Team diff --git a/doc/raster/r.example/r.example.md b/doc/raster/r.example/r.example.md new file mode 100644 index 00000000000..62a9435c93e --- /dev/null +++ b/doc/raster/r.example/r.example.md @@ -0,0 +1,29 @@ +## DESCRIPTION + +*r.example* does practically do nothing, except for illustrating GRASS +GIS raster programming. It copies over an existing raster map to a new +raster map. See the source code for details. + +## NOTES + +Some more detailed notes go here. + +## EXAMPLE + +Create a copy of the raster map "elevation" (North Carolina sample +dataset): + +```bash +g.region raster=elevation -p +r.example input=elevation output=elevation2 +r.info elevation2 +``` + +## SEE ALSO + +*[r.stats](r.stats.md), [v.example](v.example.md)* *[GRASS Programmer's +Manual](https://grass.osgeo.org/programming8/)* + +## AUTHOR + +GRASS Development Team diff --git a/doc/vector/v.example/v.example.md b/doc/vector/v.example/v.example.md new file mode 100644 index 00000000000..3b9e6d48f73 --- /dev/null +++ b/doc/vector/v.example/v.example.md @@ -0,0 +1,28 @@ +## DESCRIPTION + +*v.example* is an example vector module that does something like +labeling all vectors with value 1. A new map is written instead of +updating the input map. See the source code for details. + +## NOTES + +Some more detailed notes go here. + +## EXAMPLE + +Label all vectors with value 1 (North Carolina sample dataset): + +```bash +v.example input=zipcodes_wake output=newmap +v.category newmap option=report +``` + +## SEE ALSO + +*[r.example](r.example.md), [r.category](v.category.md), +[v.example](v.example.md)* *[GRASS Programmer's +Manual](https://grass.osgeo.org/programming8/)* + +## AUTHOR + +Radim Blazek, ITC-irst, Trento, Italy diff --git a/general/g.access/g.access.md b/general/g.access/g.access.md new file mode 100644 index 00000000000..a8b18b218ce --- /dev/null +++ b/general/g.access/g.access.md @@ -0,0 +1,39 @@ +## DESCRIPTION + +This program allows the user to control access to the current mapset. +Normally, any user can read data from any GRASS mapset. But sometimes it +is desirable to prohibit access to certain sensitive data. The +*g.access* command allows a user to restrict read and execute access to +the current mapset (see UNIX *chmod* command). *g.access* will not +modify write access to the current mapset. + +The user may, for example, allow only users in the same UNIX group to +read data files in the mapset, or restrict the mapset to personal use +only. + +## NOTES + +Under GRASS, access to the mapset PERMANENT must be open to all users. +This is because GRASS looks for the user's default geographic region +definition settings and the project TITLE in files that are stored under +the PERMANENT mapset directory. The *g.access* command, therefore, will +not allow you to restrict access to the PERMANENT mapset. + +The *[g.mapsets](g.mapsets.md)* command isn't smart enough to tell if +access to a specified mapset is restricted, and the user is therefore +allowed to include the names of restricted mapsets in his search path. +However, the data in a restricted mapset is still protected; any +attempts to look for or use data in a restricted mapset will fail. The +user will simply not see any data listed for a restricted mapset. + +UNIX filesystem access controls and *g.access* actions are not supported +by MS-Windows. + +## SEE ALSO + +UNIX manual entries for *chmod(1)* and *group(5)* +*[g.mapsets](g.mapsets.md)* + +## AUTHOR + +Michael Shapiro, U.S. Army Construction Engineering Research Laboratory diff --git a/general/g.cairocomp/g.cairocomp.md b/general/g.cairocomp/g.cairocomp.md new file mode 100644 index 00000000000..0286ec2da39 --- /dev/null +++ b/general/g.cairocomp/g.cairocomp.md @@ -0,0 +1,14 @@ +## DESCRIPTION + +*g.cairocomp* isn't meant for end users. + +*g.cairocomp* is similar to *[g.pnmcomp](g.pnmcomp.md)*, except that it +works with X Pixmaps instead of PNM files. + +## SEE ALSO + +*[g.pnmcomp](g.pnmcomp.md)* + +## AUTHOR + +Glynn Clements diff --git a/general/g.copy/g.copy.md b/general/g.copy/g.copy.md new file mode 100644 index 00000000000..482f8222001 --- /dev/null +++ b/general/g.copy/g.copy.md @@ -0,0 +1,77 @@ +## DESCRIPTION + +The *g.copy* module creates a copy of existing raster maps, vector maps, +or other elements. The copy is always created in the current mapset. The +source data can be in the current mapset, in an explicitly specified +mapset, or in a mapset which is in the current mapset search path +(typically the PERMANENT mapset). + +The maps and other elements to copy are specified in pairs +**from**,**to** according to their types. Although typically only one +map is copied in one module call, multiple pairs can be provided for +each type and multiple types can be provided at the same time. + +### Relation to mapsets + +A user may access data stored under the other mapsets listed in their +mapset search path. However, the user may only modify data stored under +their own current mapset. *g.copy* allows the user to copy existing data +files **from** other mapsets **to** the user's current mapset +(`g.mapset -p`). The files to be copied must exist in the user's current +mapset search path (`g.mapsets -p`) and project; output is sent to the +relevant data element directory(ies) under the user's current mapset. + +### Behavior on error + +Errors typically occur when a map or other element does not exist, +**from** and **to** are the same, **to** element already exists and +overwriting (e.g., by **--overwrite**) is not enabled, or the **to** +element has an illegal name. When only one map or other element is +requested to be copied and the copying is not possible or fails, an +error is reported. + +If multiple maps or other elements are copied in one command, *g.copy* +attempts to copy as much as possible even when problems occur with one +of the elements. In that case, copying of the element causing problems +is skipped, and *g.copy* proceeds with copying the remaining elements. +If nothing can be copied or an error occurred during one of the copy +operations, an error message is reported after other possible copy +operations were performed. + +## EXAMPLES + +If the user wished to copy the existing raster file *soils* to a file +called *soils.ph* and to copy an existing vector map *roads* to a file +called *rds.old*, the user could type: + +```bash +g.copy raster=soils,soils.ph +g.copy vector=roads,rds.old + +# or even combined: +g.copy raster=soils,soils.ph vector=roads,rds.old +``` + +Data files can also be specified by their mapsets. For example, the +below command copies the raster map named *soils* from the mapset +*wilson* to a new file called *soils* to be placed under the user's +current mapset: + +```bash +g.copy raster=soils@wilson,soils +``` + +If no mapset name is specified, *g.copy* searches for the named **from** +map in each of the mapset directories listed in the user's current +mapset search path in the order in which mapsets are listed there (see +*[g.mapsets](g.mapsets.md)*). + +## SEE ALSO + +*[g.access](g.access.md), [g.list](g.list.md), +[g.mapsets](g.mapsets.md), [g.remove](g.remove.md), +[g.rename](g.rename.md)* + +## AUTHOR + +Michael Shapiro, U.S. Army Construction Engineering Research Laboratory diff --git a/general/g.dirseps/g.dirseps.md b/general/g.dirseps/g.dirseps.md new file mode 100644 index 00000000000..ebe0c8c4115 --- /dev/null +++ b/general/g.dirseps/g.dirseps.md @@ -0,0 +1,9 @@ +## DESCRIPTION + +*g.dirseps* is an internal tool only. It copies input string to stdout, +changing directory separator characters as specified by flags. It is +used for interoperability between Unix and MS-Windows pathnames. + +## AUTHOR + +Paul Kelly diff --git a/general/g.filename/g.filename.md b/general/g.filename/g.filename.md new file mode 100644 index 00000000000..d7cda2620a6 --- /dev/null +++ b/general/g.filename/g.filename.md @@ -0,0 +1,58 @@ +## DESCRIPTION + +*g.filename* is designed for Bourne shell scripts that need to know the +full file name, including it's path, for mapset elements, like raster, +vector and site maps, region definitions and imagery groups. + +The list of element names to search for is not fixed; any subdirectory +of the mapset directory is a valid element name. + +However, the user can find the list of standard GRASS GIS element names +in the file `$GISBASE/etc/element_list`. This is the file which +g.remove/g.rename/g.copy use to determine which files need to be +deleted/renamed/copied for a given entity type. + +## OUTPUT + +*g.filename* writes one line to standard output: + +file='*full_file_pathname'* + +The output is a */bin/sh* command to set the variable specified by the +file *name* to the full UNIX path name for the data base file. This +variable may be set in the */bin/sh* as follows: + +```bash +eval `g.filename element=name mapset=name file=name` +``` + +## NOTES + +This module generates the filename, but does not care if the file (or +mapset or element) exists or not. This feature allows shell scripts to +create new data base files as well as use existing ones. + +If the mapset is the current mapset, *g.filename* can automatically +create the *element* specified if it doesn't already exist when **-c** +flag is used. This makes it easy to add new files to the data base +without having to worry about the existence of the required data base +directories. (This program will not create a new mapset, however, if +that specified does not currently exist.) + +This module should not be used to create directories which are at the +level of what this module refer to as files, i.e., directory which +carries a name specified by a user (such as vector map directories) +should not be created using this module. Standard library functions +coming with any given language are a more appropriate tool for that. + +The program exits with a 0 if everything is ok; it exits with a non-zero +value if there is an error, in which case file=*'full_file_pathname'* is +not output. + +## SEE ALSO + +*[g.findfile](g.findfile.md), [g.gisenv](g.gisenv.md)* + +## AUTHOR + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory diff --git a/general/g.findetc/g.findetc.md b/general/g.findetc/g.findetc.md new file mode 100644 index 00000000000..e18980986fb --- /dev/null +++ b/general/g.findetc/g.findetc.md @@ -0,0 +1,22 @@ +## DESCRIPTION + +*g.findetc* is designed for Bourne shell scripts that need to search for +support data, programs and subfoldrs in any number of directories as +specified in GRASS_ADDON_ETC, plus the GRASS application etc/ directory. +This is designed for addon scripts that are installed outside the GRASS +application directory, such as a user's home or a system addon +directory. + +## OUTPUT + +*g.findetc* writes the full path to the file or directory to standard +output + +## SEE ALSO + +*[g.filename](g.filename.md), [g.findfile](g.findfile.md), +[g.gisenv](g.gisenv.md), [g.mapsets](g.mapsets.md)* + +## AUTHOR + +William Kyngesburye diff --git a/general/g.findfile/g.findfile.md b/general/g.findfile/g.findfile.md new file mode 100644 index 00000000000..755b28cc208 --- /dev/null +++ b/general/g.findfile/g.findfile.md @@ -0,0 +1,97 @@ +## DESCRIPTION + +*g.findfile* is designed for Bourne shell or Python scripts that need to +search for mapset *elements*, including: raster, vector maps, region +definitions and *[imagery](i.group.md)* groups. + +The list of **element** names to search for is not fixed; any +subdirectory of the mapset directory is a valid **element** name. + +However, the user can find the list of standard GRASS **element** names +in the file `$GISBASE/etc/element_list`. This is the file which +*[g.remove](g.remove.md)*, *[g.rename](g.rename.md)* and +*[g.copy](g.copy.md)* use to determine which files need to be +deleted/renamed/copied for a given entity type. + +## NOTES + +*g.findfile* writes four lines to standard output: + +```bash +name='file_name' +mapset='mapset_name' +file='unix_filename' +fullname='grass_fullname' +``` + +The output is *Bash* commands to set the variable *name* to the GRASS +data base file name, *mapset* to the mapset in which the file resides, +and *file* to the full UNIX path name for the named file. These +variables may be set in the *Bash* as follows: + +```bash +eval `g.findfile element=name mapset=name file=name` +``` + +## EXAMPLES + +### SHELL + +**Raster map example:** + +```bash +eval `g.findfile element=cell file=elevation` +``` + +If the specified file (here: raster map) does not exist, the variables +will be set as follows: + +```bash +name= +mapset= +fullname= +file= +``` + +The following is a way to test for this case: + +```bash +if [ ! "$file" ] +then + exit 1 +fi +``` + +**Vector map example (including error message):** + +```bash +eval `g.findfile element=vector file="$G_OPT_V_INPUT"` +if [ ! "$file" ] ; then + g.message -e "Vector map <$G_OPT_V_INPUT> not found" + exit 1 +fi +``` + +### PYTHON + +See *[Python Scripting +Library](https://grass.osgeo.org/grass-devel/manuals/libpython/)* for +more info. + +Note: The Python tab in the *wxGUI* can be used for entering the +following code: + +```bash +import grass.script as gcore + +gcore.find_file('elevation', element = 'cell') +``` + +## SEE ALSO + +*[g.filename](g.filename.md), [g.gisenv](g.gisenv.md), +[g.mapsets](g.mapsets.md), [g.parser](g.parser.md)* + +## AUTHOR + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory diff --git a/general/g.gisenv/g.gisenv.md b/general/g.gisenv/g.gisenv.md new file mode 100644 index 00000000000..3d0936a8b2e --- /dev/null +++ b/general/g.gisenv/g.gisenv.md @@ -0,0 +1,186 @@ +## DESCRIPTION + +*g.gisenv* outputs and modifies the user's current GRASS GIS variable +settings. When a user runs GRASS, certain variables are set specifying +the GRASS data base, project, mapset, peripheral device drivers, etc., +being used in the current GRASS session. These variable name settings +are recognized as long as the user is running a GRASS session. + +## OPTIONS + +No prompts are given to the user when running *g.gisenv*. + +If run without arguments, *g.gisenv* lists all of the user's current +GRASS variable settings. Results are sent to standard output, and may +look like this: + +```bash +GISDBASE=/opt/grassdata/ +LOCATION_NAME=nc_spm_08_grass7 +MAPSET=/user1 +GUI=gui +``` + +If the user specifies a **get=***variable_name* on the command line + +```bash +g.gisenv MAPSET +``` + +only the value for that particular GRASS variable is output to standard +output. Possible variable names depend on the user's system, see +[variables list](variables.md) for details. Note that the variable names +are case-insensitive. + +While other variables may be associated with each GRASS session (e.g., +GRASS_GUI, GIS_LOCK, and other variables), those stated below are +essential. + +*GISDBASE* +The *GISDBASE* is a directory in which all users' GRASS data are stored. +Within the *GISDBASE*, data are segregated into subdirectories (called +"projects") based on the map coordinate system used and the geographic +extent of the data. Each "project" directory itself contains +subdirectories called "mapsets"; each "mapset" stores "data base +elements" - the directories (e.g., the `cell`, `cellhd`, `vector`, etc., +directories) in which GRASS data files are actually stored. + +*LOCATION_NAME* +The user must choose to work with the data under a single GRASS project +(previously called "location") within any given GRASS session; this +project is then called the *current GRASS project*, and is specified by +the variable *LOCATION_NAME*. The *LOCATION_NAME* is the GRASS data base +location whose data will be affected by any GRASS commands issued during +the user's current GRASS session, and is a subdirectory of the current +*GISDBASE*. Each "project" directory can contain multiple "mapset" +directories (including the special mapset *PERMANENT*). Maps stored +under the same GRASS *LOCATION_NAME* (and/or within the same *MAPSET*) +must use the same coordinate system and typically fall within the +boundaries of the same geographic region. + +*MAPSET* +Each "mapset" contains a set of maps relevant to the *LOCATION_NAME* +directory in which it appears. Each *LOCATION_NAME* can contain multiple +mapsets. (Mapsets which fall under the same *LOCATION_NAME* all contain +data geographically relevant to the *LOCATION_NAME*, and all store data +in the same map coordinate system. Frequently, maps are placed into +different mapsets to distinguish file ownership - e.g., each user might +have one or more own mapset(s), storing any maps that the user has +created and/or are relevant to the own work.) During each GRASS session, +the user must choose one mapset to be the *current mapset*; the current +mapset setting is given by *MAPSET*, and is a subdirectory of +*LOCATION_NAME*. During a single GRASS session, the user can use +available data in any of the mapsets stored under the current +*LOCATION_NAME* directory that are in the user's mapset search path and +accessible by the user. However, within a single GRASS session, the user +only has *write* access to data stored under the *current mapset* +(specified by the variable *MAPSET*). + +Each "mapset" stores GRASS data base elements (i.e., the directories in +which GRASS data files are stored). Any maps created or modified by the +user in the current GRASS session will be stored here. The *MAPSET* +directory *PERMANENT* is generally reserved for the set of maps that +form the base set for all users working under each *LOCATION_NAME*. + +Once within a GRASS session, GRASS users have access only to the data +under a single GRASS data base directory (the *current GRASS data base*, +specified by the variable *GISDBASE*), and to a single GRASS project +directory (the *current project*, specified by the variable +*LOCATION_NAME*). Within a single session, the user may only *modify* +the data in the *current mapset* (specified by the variable *MAPSET*), +but may *use* data available under other mapsets under the same +*LOCATION_NAME*. + +All of these names must be legal names on the user's current system. + +The full path to the current mapset is determined from *GISDBASE*, +*LOCATION_NAME*, *MAPSET* variables, in the example above: +`/opt/grassdata/spearfish/PERMANENT`. The full path can be printed using +*g.gisenv* by providing multiple variables: + +```bash +g.gisenv get=GISDBASE,LOCATION_NAME,MAPSET sep='/' +/opt/grassdata/nc_spm_08_grass7/user1 +``` + +## NOTES + +The output from *g.gisenv* when invoked without arguments is directly +usable by Bash. The following command will cast each variable into the +UNIX environment: + +```bash +eval `g.gisenv` +``` + +This works only for *Bash*, *sh*, *ksh*, etc. The format of the output +is not compatible with some other UNIX shells. + +By default the GRASS variables are stored in *gisrc* file (defined by +environmental variable *GISRC*). If **store=mapset** is given then the +variables are stored in `///VAR` after the +current GRASS session is closed. + +## EXAMPLES + +### Cache for raster operations + +The maximum memory to be used, i.e. the cache size for raster rows, is +set to 300 MB by default (GRASS variable *MEMORYMB*). To speed up raster +operations, it is recommended to increase this setting if enough RAM is +available. It is important to note that parallel processes will each +consume this amount of RAM. Set the maximum memory to be used (in MB), +i.e. the cache size for raster rows: + +```bash +# set to 6 GB (default: 300 MB) +g.gisenv set="MEMORYMB=6000" +``` + +### Number of threads for parallel computing + +Set the number of threads for parallel computing: + +```bash +# set to use 12 threads (default: 1) +g.gisenv set="NPROCS=12" +``` + +### GRASS Debugging + +To print debugging messages, the variable *DEBUG* must be set to level +equal or greater than 0: + +```bash +g.gisenv set="DEBUG=3" +``` + +Levels: (recommended levels) + +- 0 - silence +- 1 - message is printed once or few times per module +- 3 - each row (raster) or line (vector) +- 5 - each cell (raster) or point (vector) + +To disable debugging messages: + +```bash +g.gisenv unset="DEBUG" +``` + +The variable DEBUG controls debugging messages from GRASS libraries and +modules. + +Similarly *WX_DEBUG* controls debugging messages from [wxGUI](wxGUI.md). + +## SEE ALSO + +*[g.access](g.access.md), [g.filename](g.filename.md), +[g.findfile](g.findfile.md), [g.mapsets](g.mapsets.md)* + +See also [list of selected GRASS gisenv +variables](variables.md#list-of-selected-grass-gisenv-variables) + +## AUTHOR + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory diff --git a/general/g.gui/g.gui.md b/general/g.gui/g.gui.md new file mode 100644 index 00000000000..b7ed05ca34b --- /dev/null +++ b/general/g.gui/g.gui.md @@ -0,0 +1,67 @@ +## DESCRIPTION + +The *g.gui* module allows user to start the Graphical User Interface +(GUI) from the command line prompt or to change the default User +Interface (UI) settings. + +GRASS GIS comes with both a wxPython-based GUI aka *[wxGUI](wxGUI.md)* +(**ui=wxpython**) and command line text-based UI (**ui=text**). + +## NOTES + +If the **-d** update flag is given or the `GRASS_GUI` environmental +[variable](variables.md) is unset, then the GRASS internal variable +`GUI` is permanently changed and the selected **ui** will be used as the +default UI from then on. + +All GRASS internal variables (see *[g.gisenv](g.gisenv.md)*) are stored +in the user's home directory in a hidden file called `$HOME/.grass8/rc` +on Unix-based operating systems and `%APPDATA%\GRASS8\rc` on MS Windows. +Note that these GRASS internal variables are not the shell environment +variables and the `rc` file is not a classic UNIX run command file, it +just contains persistent GRASS variables. + +## EXAMPLES + +### Set default user interface settings + +Set default user interface setting to command line, text-based UI: + +```bash +g.gui -d ui=text +``` + +Set default user interface setting to the graphical user interface (GUI) +and *launch* the GUI: + +```bash +g.gui -d ui=wxpython +``` + +Set default user interface setting to the graphical user interface (GUI) +but *do not launch* the GUI: + +```bash +g.gui -dn ui=wxpython +``` + +### Load workspace from command line + +Start the GUI from command line with an existing workspace: + +```bash +g.gui workspace=myproject.gxw +``` + +## SEE ALSO + +*[wxGUI](wxGUI.md), [g.gisenv](g.gisenv.md), [GRASS +variables](variables.md)* + +[wxGUI wiki +page](https://grasswiki.osgeo.org/wiki/WxPython-based_GUI_for_GRASS) + +## AUTHORS + +Martin Landa, FBK-irst, Trento, Italy +Hamish Bowman, Otago University, Dunedin, New Zealand (fine tuning) diff --git a/general/g.list/g.list.md b/general/g.list/g.list.md new file mode 100644 index 00000000000..1ac1955df73 --- /dev/null +++ b/general/g.list/g.list.md @@ -0,0 +1,212 @@ +## DESCRIPTION + +*g.list* searches for data files matching a pattern given by wildcards +or POSIX Extended Regular Expressions. + +## NOTES + +The output of *g.list* may be useful for other programs' parameter input +(e.g. time series for *[r.series](r.series.md)*) when used with +*separator=comma*. + +## EXAMPLES + +List all raster maps as continuous, sorted list: + +```bash +g.list type=rast +``` + +List all vector maps as continuous, sorted list with MAPSET info (i.e. +fully-qualified map names): + +```bash +g.list type=vector -m +``` + +List all raster and vector maps ordered by mapset: + +```bash +g.list type=raster -p +``` + +List all raster and vector maps as continuous, sorted list: + +```bash +g.list type=rast,vect +``` + +List all available GRASS data base files: + +```bash +g.list type=all +``` + +### Mapset search path + +If **mapset** is not specified, then *g.list* searches for data files in +the mapsets that are included in the search path (defined by +*[g.mapsets](g.mapsets.md)*). See `g.mapsets -p`. + +```bash +g.list rast -p + +raster map(s) available in mapset : +dmt +... +raster map(s) available in mapset : +aspect +... +``` + +Option **mapset**=. (one dot) lists only data files from the current +mapset: + +```bash +g.list rast mapset=. +... +``` + +Similarly, **mapset**=\* (one asterisk) prints data files from all +available mapsets also including those that are not listed in the +current search path (see `g.mapsets -l`). + +```bash +g.list rast mapset=* -p + +raster map(s) available in mapset : +lsat5_1987_10 +... +raster map(s) available in mapset : +dmt +... +raster map(s) available in mapset : +aspect +... +``` + +### Wildcards + +List all vector maps starting with letter "r": + +```bash +g.list type=vector pattern="r*" +``` + +List all vector maps starting with letter "r" or "a": + +```bash +g.list type=vector pattern="[ra]*" +``` + +List all raster maps starting with "soil\_" or "landuse\_": + +```bash +g.list type=raster pattern="{soil,landuse}_*" +``` + +List certain raster maps with one variable character/number: + +```bash +g.list type=raster pattern="N45E00?.meters" +``` + +Use of **exclude** parameter: + +```bash +# without exclude: + g.list rast pat="r*" mapset=PERMANENT + railroads + roads + rstrct.areas + rushmore + +# exclude only complete word(s): + g.list rast pat="r*" exclude=roads mapset=PERMANENT + railroads + rstrct.areas + rushmore + +# exclude with wildcard: + g.list rast pat="r*" exclude="*roads*" mapset=PERMANENT + rstrct.areas + rushmore +``` + +### Regular expressions + +List all soil maps starting with "soils" in their name: + +```bash +g.list -r type=raster pattern='^soils' +``` + +List "tmp" if "tmp" raster map exists: + +```bash +g.list -r type=raster pattern='^tmp$' +``` + +List "tmp0" ..."tmp9" if corresponding vector map exists (each map name +linewise): + +```bash +g.list -r type=vector pattern='^tmp[0-9]$' +``` + +List "tmp0"..."tmp9" if corresponding vector map exists (each map name +comma separated): + +```bash +g.list -r type=vector separator=comma pattern='^tmp[0-9]$' +``` + +### Extended regular expressions + +List all precipitation maps for the years 1997-2012, comma separated: + +```bash +g.list -e type=raster separator=comma pattern="precip_total.(199[7-9]|200[0-9]|201[0-2]).sum" +``` + +### Maps whose region overlaps with a saved region + +List all raster maps starting with "tmp\_" whose region overlaps with +the region of "test" raster map: + +```bash +g.region raster=test save=test_region +g.list type=raster pattern='tmp_*' region=test_region +``` + +List "tmp0"..."tmp9" vector maps whose region overlaps with the current +region: + +```bash +g.list -r type=vector pattern='^tmp[0-9]$' region=. +``` + +List all raster and vector maps whose region overlaps with the default +region of the PERMANENT mapset in the current project (DEFAULT_WIND): + +```bash +g.list type=rast,vect region=* +``` + +Note that, without `region=*`, `g.list type=rast,vect` simply lists all +available raster and vector maps from the current search path regardless +of their region. + +## SEE ALSO + +*[r.series](r.series.md), [t.list](t.list.md), +[t.rast.list](t.rast.list.md), [t.vect.list](t.vect.list.md)* + +[Regular expressions](https://en.wikipedia.org/wiki/Regular_expression) +(aka regex) - from Wikipedia, the free encyclopedia + +## AUTHOR + +Huidae Cho + +based on general/manage/cmd/list.c by Michael Shapiro diff --git a/general/g.mapset/g.mapset.md b/general/g.mapset/g.mapset.md new file mode 100644 index 00000000000..a563c1acfe9 --- /dev/null +++ b/general/g.mapset/g.mapset.md @@ -0,0 +1,69 @@ +## DESCRIPTION + +*g.mapset* changes the current working mapset, project (formerly known +as location), or GISDBASE (directory with one or more projects). + +With *g.mapset*, the shell history (i.e. `.bash_history` file of the +initial project will be used to record the command history. + +## NOTES + +By default, the shell continues to use the history for the old mapset. +To change this behaviour the history can be switched to record in the +new mapset's history file as follows: + +```bash +# bash example +history -w +history -r /"$GISDBASE/$LOCATION/$MAPSET"/.bash_history +HISTFILE=/"$GISDBASE/$LOCATION/$MAPSET"/.bash_history +``` + +## EXAMPLES + +### Print the name of the current mapset + +To print the name of the current mapset, use the **-p** command as shown +below: + +```bash +g.mapset -p +``` + +### List available mapsets + +To list available mapsets, use the **-l** command as shown below: + +```bash +g.mapset -l +``` + +This should list all the mapsets, such as: "landsat new PERMANENT +user1." + +### Change the current mapset + +To change the current mapset to "user1" use the following command: + +```bash +g.mapset mapset=user1 project=nc_spm_08_grass7 +``` + +You should receive the following message: "Mapset switched. Your shell +continues to use the history for the old mapset." + +### Create a new mapset + +To create a new mapset, use the **-c** tag as shown below: + +```bash +g.mapset -c mapset=new project=nc_spm_08_grass7 +``` + +## SEE ALSO + +*[g.gisenv](g.gisenv.md), [g.mapsets](g.mapsets.md)* + +## AUTHOR + +Radim Blazek diff --git a/general/g.mapsets/g.mapsets.md b/general/g.mapsets/g.mapsets.md new file mode 100644 index 00000000000..e30141a0a93 --- /dev/null +++ b/general/g.mapsets/g.mapsets.md @@ -0,0 +1,181 @@ +## DESCRIPTION + +*g.mapsets* modifies/prints the user's current mapset search path. For +basic information about GRASS *mapset*, *project* and *data base* refer +to [GRASS Quickstart](helptext.md). + +A *mapset* holds a distinct set of data layers, each relevant to the +same (or a subset of the same) geographic region, and each drawn in the +same map coordinate system. At the outset of every GRASS session, the +user identifies a GRASS data base, project (previosuly called location), +and mapset that are to be the user's *current data base*, *current +project*, and *current mapset* for the duration of the session; any maps +created by the user during the session will be stored under the *current +mapset* set at the session's outset (see *[g.mapset](g.mapset.md)* +\[without an "s"\] and *[g.gisenv](g.gisenv.md)* for changing the mapset +with a session). + +The user can add, modify, and delete data layers that exist under their +*current mapset*. Although the user can also *access* (i.e., use) data +that are stored under *other* mapsets in the same GRASS project using +the `mapname@mapsetname` notation or mapset search path, the user can +only make permanent changes (create or modify data) located in the +*current mapset*. The user's *mapset search path* lists the order in +which other mapsets in the same GRASS project can be searched and their +data accessed by the user. The user can modify the listing and order in +which these mapsets are accessed by modifying the mapset search path; +this can be done using the *g.mapsets* command. This program allows the +user to use other's relevant map data without altering the original data +layer, and without taking up disk space with a copy of the original map. +The `mapname@mapsetname` notation may be used irrespective of the mapset +search path, i.e., any map found in another mapset with sufficient +*[g.access](g.access.md)* privileges may be called in such a manner. + +*g.mapsets* shows the user available mapsets under the current GRASS +project, lists mapsets to which the user currently has access, and lists +the order in which accessible mapsets will be accessed by GRASS programs +searching for data files. The user is then given the opportunity to add +or delete mapset names from the search path, or modify the order in +which mapsets will be accessed. + +When the user specifies the name of a data base element file (e.g., a +particular vector map, raster map, [imagery](i.group.md) group file, +etc.) to a GRASS program, the program searches for the named file under +each of the mapsets listed in the user's mapset search path in the order +listed there until the program finds a file of the given name. Users can +also specify a file by its mapset, to make explicit the mapset from +which the file is to be drawn; e.g., the command: + +```bash +g.copy raster=soils@PERMANENT,my_soils +``` + +ensures that a new file named `my_soils` is to be a copy of the file +`soils` from the mapset PERMANENT. + +In each project there is the special mapset **PERMANENT** included in +the mapset search path, as this mapset typically contains base maps +relevant to many applications. Often, other mapsets which contain sets +of interpreted maps will be likewise included in the user's mapset +search path. Suppose, for example, that the mapset *Soil_Maps* contains +interpreted soils map layers to which the user wants access. The mapset +*Soil_Maps* should then be included in the user's *search path* +variable. + +The *mapset search path* is saved as part of the current mapset. When +the user works with that mapset in subsequent GRASS sessions, the +previously saved mapset search path will be used (and will continue to +be used until it is modified by the user with *g.mapsets*). + +## NOTES + +By default *g.mapsets* adds to the current *mapset search path* mapsets +named by **mapset** option. Alternatively mapsets can be removed +(**operation=remove**) from the search path or defined by +**operation=set**. + +Users can restrict others' access to their mapset files through use of +*[g.access](g.access.md)*. Mapsets to which access is restricted can +still be listed in another's mapset search path; however, access to +these mapsets will remain restricted. + +## EXAMPLES + +### Selecting mapsets with the graphical mapset manager + +Using the **-s** flag, a convenient graphical mapset manager can be +opened to select and deselect other mapsets (the actual mapset and the +PERMANENT mapset are always selected): + +```bash +g.mapsets -s +``` + +![](g_mapsets_gui.png) + +### Print available mapsets + +All available mapsets in the current project can be printed out by + +```bash +g.mapsets -l + +Available mapsets: +PERMANENT user1 user2 +``` + +Mapsets can be also printed out as json by setting the format option to +"json" (**format="json"**). + +
+ +```bash + g.mapsets format="json" -l + + { + "mapsets": [ + "PERMANENT", + "user1", + "user2" + ] + } + +``` + +
+ +### Add new mapset + +Add mapset 'user2' to the current mapset search path + +```bash +g.mapsets mapset=user2 operation=add +``` + +The current mapset search path is changed accordingly + +```bash +g.mapsets -p + +Accessible mapsets: +user1 user2 +``` + +### Overwrite current search path + +Overwrite current search path + +```bash +g.mapsets mapset=user1,PERMANENT operation=set +``` + +### Using shortcuts for search path + +The current mapset can be defined by a shortcut "." (dot) + +```bash +g.mapsets mapset=.,PERMANENT operation=set +``` + +*Note:* The current mapset will be always included in the search path on +the first position even if you change its position or omit the current +mapset from the **mapset** option. + +```bash +g.mapsets -p + +Accessible mapsets: +user1 PERMANENT +``` + +## SEE ALSO + +*[g.access](g.access.md), [g.copy](g.copy.md), [g.gisenv](g.gisenv.md), +[g.list](g.list.md), [g.mapset](g.mapset.md)* + +## AUTHORS + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory +Greg Koerper, ManTech Environmental Technology, Inc. +Updated to GRASS 7 by Martin Landa, Czech Technical University in +Prague, Czech Republic diff --git a/general/g.message/g.message.md b/general/g.message/g.message.md new file mode 100644 index 00000000000..3b8cbe018d0 --- /dev/null +++ b/general/g.message/g.message.md @@ -0,0 +1,138 @@ +## DESCRIPTION + +*g.message* prints a message, warning, progress info, or fatal error in +the GRASS GIS way. This program is to be used in Shell/Perl/Python +scripts, so the author does not need to use the `echo` program. The +advantage of *g.message* is that it formats messages just like other +GRASS modules do and that its functionality is influenced by the +`GRASS_VERBOSE` and `GRASS_MESSAGE_FORMAT` environment variables. + +The program can be used for standard informative messages as well as +warnings (**-w** flag) and fatal errors (**-e** flag). For debugging +purposes, the **-d** flag will cause *g.message* to print a debugging +message at the given level. + +## NOTES + +Messages containing "`=`" must use the full **message=** syntax so the +parser doesn't get confused. + +If you want a long message (multi-line) to be dealt with as a single +paragraph, use a single call to *g.message* with text split in the +script using the backslash as the last character. (In shell scripts +don't close the "quote") + +A blank line may be obtained with + +```bash +g.message message="" +``` + +Redundant whitespace will be stripped away. + +It's advisable to single quote the messages that are to be printed +literally. It prevents a number of characters (most notably, space and +the dollar sign '`$`') from being treated specifically by the shell. + +When it is necessary to include, for example, a variable's value as part +of the message, the double quotes may be used, which do not deprive the +dollar sign of its special variable-expansion powers. + +While it is known that the interactive Bash instances may treat the +exclamation mark '`!`' character specifically (making single quoting of +it necessary), it shouldn't be the case for the non-interactive +instances of Bash. Nonetheless, to avoid context-based confusion later +on you are encouraged to single-quote messages that do not require +`$VARIABLE` expansion. + +### Usage in Python scripts + +[GRASS Python Scripting +Library](https://grass.osgeo.org/grass-devel/manuals/libpython/) defines +special wrappers for *g.message*. + +- `debug()` for `g.message -d` +- `error()` for `g.message -e` +- `fatal()` for `g.message -e` + `exit()` +- `info()` for `g.message -i` +- `message()` for `g.message` +- `verbose()` for `g.message -v` +- `warning()` for `g.message -w` + +Note: The Python tab in the *wxGUI* can be used for entering the +following sample code: + +```bash +import grass.script as gcore + +gcore.warning("This is a warning") +``` + +is identical with + +```bash +g.message -w message="This is a warning" +``` + +### VERBOSITY LEVELS + +Controlled by the "`GRASS_VERBOSE`" environment variable. Typically this +is set using the **--quiet** or **--verbose** command line options. + +- 0 - only errors and warnings are printed +- 1 - progress messages are printed +- 2 - all module messages are printed +- 3 - additional verbose messages are printed + +### DEBUG LEVELS + +Controlled by the "`DEBUG`" GRASS *gisenv* variable (set with +*[g.gisenv](g.gisenv.md)*). +Recommended levels: + +- 1 - message is printed once or few times per module +- 3 - each row (raster) or line (vector) +- 5 - each cell (raster) or point (vector) + +## EXAMPLES + +This basic example prints the message "hello" in the console: + +```bash +g.message message="hello" +``` + +To print a message as an error message use the **-e** flag: + +```bash +g.message -e message="my error" +``` + +To print a message highlighted as a debug message ("D0/0: debug") in the +console, use the **-d** flag. Optionally the debug level can be defined +(see also [g.gisenv](g.gisenv.md) for details): + +```bash +# Levels: (recommended levels) +# 0 - silence +# 1 - message is printed once or few times per module +# 3 - each row (raster) or line (vector) +# 5 - each cell (raster) or point (vector) +g.message -d message="debug" debug=0 +``` + +To print a message highlighted as a warning message ("WARNING: my +warning") in the console, use the **-w** flag: + +```bash +g.message -w message="my warning" +``` + +## SEE ALSO + +*[GRASS variables and environment variables](variables.md)* +*[g.gisenv](g.gisenv.md), [g.parser](g.parser.md)* + +## AUTHOR + +Jachym Cepicky diff --git a/general/g.mkfontcap/g.mkfontcap.md b/general/g.mkfontcap/g.mkfontcap.md new file mode 100644 index 00000000000..5ead54e79a3 --- /dev/null +++ b/general/g.mkfontcap/g.mkfontcap.md @@ -0,0 +1,56 @@ +## DESCRIPTION + +*g.mkfontcap* is a utility to generate a GRASS font configuration file +("fontcap") containing details of the fonts available on the current +system. If [Freetype](https://freetype.org/) is not installed, the font +list will be limited to the set of Hershey stroke fonts supplied with +GRASS. With Freetype enabled however, the module will recursively scan +all files within a predefined hierarchy to find Freetype-compatible +scalable fonts. The list of directories scanned is currently: + +```bash + /usr/lib/X11/fonts + /usr/share/X11/fonts + /usr/share/fonts + /usr/local/share/fonts + ${HOME}/Library/Fonts + /Library/Fonts + /System/Library/Fonts + ${WINDIR}/Fonts +``` + +These correspond to directories where fonts can be found on some common +operating systems. Extra directories to search can easily by added using +the **extradirs** parameter, which accepts a comma-separated list. An +extra directory may optionally contain an environment variable *at the +start* of the string, if enclosed in ${xxx} syntax (see examples +above). + +The module will normally write to the standard fontcap file location, +`$GISBASE/etc/fontcap`. If the environment variable `GRASS_FONT_CAP` is +set, the output will instead be written to the file specified by that +variable. This is useful if you don't have permission to modify +`$GISBASE/etc/fontcap`: in this case you can use e.g. + +```bash +# use local file version instead of system copy +GRASS_FONT_CAP=$HOME/.gfontcap +export GRASS_FONT_CAP + +g.mkfontcap +``` + +to create a personal copy and then to make GRASS use that file instead +of the system copy. + +The output list of fonts is sorted first by type (Stroke fonts first, +followed by Freetype) and within each type by the short name of the +font. + +## SEE ALSO + +*[d.font](d.font.md)* + +## AUTHOR + +Paul Kelly diff --git a/general/g.parser/g.parser.md b/general/g.parser/g.parser.md new file mode 100644 index 00000000000..003155ea047 --- /dev/null +++ b/general/g.parser/g.parser.md @@ -0,0 +1,665 @@ +## KEYWORDS + +[general](general.md), [support](topic_support.md), +[scripts](keywords.md#scripts) + +## SYNOPSIS + +**g.parser --help** +**g.parser** \[-**s**\] \[-**t**\] \[-**n**\] *filename* +\[*argument*,...\] + +### Flags + +**-t** +Print strings for translation + +**-s** +Write option values to standard output instead of reinvoking script + +**-n** +Write option values to standard output separated by null character + +## DESCRIPTION + +The *g.parser* module provides full parser support for GRASS scripts, +including an auto-generated GUI interface, help page template, and +command line option checking. In this way a simple script can very +quickly be made into a full-fledged GRASS module. + +## OPTIONS + +Unless the **-s** or **-n** switch is used, the arguments are stored in +environment variables for use in your scripts. These variables are named +"GIS_FLAG\_\" for flags and "GIS_OPT\_\" for options. The +names of variables are converted to upper case. For example if an option +with key **input** was defined in the script header, the value will be +available in variable **GIS_OPT_INPUT** and the value of flag with key +**f** will be available in variable **GIS_FLAG_F**. + +For flags, the value will be "1" if the flag was given, and "0" +otherwise. + +If the **-s** or **-n** switch is used, the options and flags are +written to standard output in the form *opt\_\=\* and +*flag\_\=\*, preceded by the string **@ARGS_PARSED@**. If +this string doesn't appear as the first line of standard output, it +indicates that the script was invoked with a switch such as +**--html-description**. In this case, the data written by *g.parser* to +standard output should be copied to the script's standard output +verbatim. If the **-s** switch is used, the options and flags are +separated by newlines. If the **-n** switch is used, the options and +flags are separated by null characters. + +Typical header definitions are as follows: + +```bash +# %module +# % description: g.parser test script +# %end +# %flag +# % key: f +# % description: A flag +# %end +# %option +# % key: raster +# % type: string +# % gisprompt: old,cell,raster +# % description: Raster input map +# % required: yes +# %end +``` + +With `{NULL}` it is possible to suppress a predefined `description` or +`label`. + +The parsers allows using predefined *standardized options and flags*, +see the list of +[options](https://grass.osgeo.org/programming8/parser__standard__options_8c.html#a1a5da9db1229a9bbc59d16ae84540bb8) +and +[flags](https://grass.osgeo.org/programming8/parser__standard__options_8c.html#ad081e95e5d4dc3daab9c820d962e6902) +in the programmer manual. Eg. the option + +```bash +# %option +# % key: raster +# % type: string +# % gisprompt: old,cell,raster +# % description: Raster input map +# % required: yes +# %end +``` + +can be easily defined as + +```bash +# %option G_OPT_R_MAP +# % key: raster +# %end +``` + +The parser allows defining predefined *rules* for used options. The +syntax of the rules section is following: + +```bash +# %rules +# % exclusive: capfile_output, capfile +# %end +``` + +The parser also allows defining "OR" conditions, e.g. requiring raster +OR vector (for details, see below), e.g.for options: + +```bash +# %rules +# % required: raster, vector +# %end +``` + +and e.g., for flags: + +```bash +# %rules +# % required: -i,-d,-c +# %end +``` + +## NOTES + +An option can be instructed to allow multiple inputs by adding the +following line: + +```bash +# % multiple: yes +``` + +While this will only directly change the *Usage* section of the help +screen, the option's environmental string may be easily parsed from +within a script. For example, individual comma separated identities for +an option named "input" can be parsed with the following Bash shell +code: + +```bash +IFS=, +for opt in $GIS_OPT_INPUT ; do + ... "$opt" +done +``` + +A "`guisection`" field may be added to each option and flag to specify +that the options should appear in multiple tabs in the auto-generated +GUI. Any options without a `guisection` field go into the "Required" or +"Options" tab. For example: + +```bash +# % guisection: tabname +``` + +would put that option in a tab named *tabname*. + +A "`key_desc`" field may be added to each option to specify the text +that appears in the module's usage help section. For example: + +```bash +# % key_desc: filename +``` + +added to an **input** option would create the usage summary +`[input=filename]`. + +If a script is run with **--o**, the parser will set +`GRASS_OVERWRITE=1`, which has the same effect as passing **--o** to +every module which is run from the script. Similarly, passing **--q** or +**--v** will set `GRASS_VERBOSE` to 0 or 3 respectively, which has the +same effect as passing **--q** or **--v** to every module which is run +from the script. Rather than checking whether **--o**, **--q** or +**--v** were used, you should be checking `GRASS_OVERWRITE` and/or +`GRASS_VERBOSE` instead. If those variables are set, the script should +behave the same way regardless of whether they were set by **--o**, +**--q** or **--v** being passed to the script or set by other means. + +For backwards compatibility reasons, the header definitions can use `#%` +instead of `# %` as in `#% multiple: yes`. However, Python code should +use `# %` in order to conform to PEP8. + +## Conditional parameters + +Marking an option as "required" will result in the parser raising a +fatal error if the option is not given, with one exception: if a flag +has the `suppress_required` option, and that flag is given, all +requirements are ignored. This feature is intended for flags which +abandon "normal operation" for the module; e.g. *r.in.gdal*'s **-f** +flag (list supported formats) uses it. +But in general, an option cannot be marked as required if it is optional +except for the special case of a `suppress_required` flag. The parser +has the ability to specify option relationships. + +For C, the relevant functions are those in +[lib/gis/parser_dependencies.c](https://grass.osgeo.org/programming8/parser__dependencies_8c.html). + +For scripts, relationships are specified using a "rules" section, e.g. + +```bash +# %rules +# % required: altitude,elevation +# %end +``` + +specifies that at least one of those options must be given. Both options +and flags can be specified (a leading "**-**" denotes a flag). The +available rule types are: + +- `exclusive`: at most one of the options may be given +- `required`: at least one of the options must be given +- `requires`: if the first option is given, at least one of the + subsequent options must also be given +- `requires_all`: if the first option is given, all of the subsequent + options must also be given +- `excludes`: if the first option is given, none of the subsequent + options may be given +- `collective`: all or nothing; if any option is given, all must be + given + +## AUTOMATED SCRIPT CREATION + +The flag **--script** added to a GRASS command, generates shell output. +To write out a *g.parser* boilerplate for easy prototyping of Python +scripts, the flag **--script** can be added to any GRASS command. +Example: + +```bash +v.in.db --script +``` + +## Help page template (HTML) + +The flag **--html-description** added to a GRASS command generates a +related help page template in HTML. Example: + +```bash +v.in.db --html-description +``` + +## GUI window parser (XML) + +The flag **--interface-description** added to a GRASS command generates +a related help page template in XML. Example: + +```bash +v.in.db --interface-description +``` + +## JSON + +The flag **--json** added to a GRASS command with parameters mandatorily +to be specified generates a module interface description in JSON. +Example: + +```bash +v.in.db driver=sqlite database=mysqlite.db table=pointsfile x=x y=y z=z key=idcol out=dtmpoints --json +{ + "module": "v.in.db", + "id": "v.in.db_1804289383", + "inputs":[ + {"param": "table", "value": "pointsfile"}, + {"param": "driver", "value": "sqlite"}, + {"param": "database", "value": "mysqlite.db"}, + {"param": "x", "value": "x"}, + {"param": "y", "value": "y"}, + {"param": "z", "value": "z"}, + {"param": "key", "value": "idcol"} + ], + "outputs":[ + {"param": "output", "value": "dtmpoints"} + ] +} +``` + +## Web Processing Service (WPS) + +The flag **--wps-process-description** added to a GRASS command +generates a Web Processing Service process description. Example: + +```bash +v.in.db --wps-process-description +``` + +## reStructuredText + +The flag **--rst-description** added to a GRASS command generates module +interface description in reStructuredText, a lightweight markup +language. Example: + +```bash +v.in.db --rst-description +``` + +reStructuredText is sometimes abbreviated as reST, ReST, or RST. The +commonly used file extension is `.rst`. Don't be confused with +Representational State Transfer (REST) technology. + +## TRANSLATION + +*g.parser* provides some support for translating the options of scripts. +If called with the -t switch before the script filename like this + +```bash +g.parser -t somescriptfile +``` + +*g.parser* will print the text of the translatable options to standard +output, one per line, and exit. This is for internal use within the +build system to prepare GRASS scripts for translation. + +## EXAMPLES + +All examples below autogenerate the graphical user interface when +invoked without parameters of flags: + +![Autogenerated GUI window](g_parser_test.png) + +To run properly, the script needs to be copied into a directory listed +in `$GRASS_ADDON_PATH` environmental variable with the executable flag +being set. + +The script will provide a GUI (as above) and the following usage help +text: + +```bash +test.py|sh|pl --help + +Description: + g.parser test script (python) + +Usage: + test.sh [-f] raster=string vector=string [option1=string] + [--verbose] [--quiet] + +Flags: + -f A flag + --v Verbose module output + --q Quiet module output + +Parameters: + raster Raster input map + vector Vector input map + option1 An option +``` + +### Example code for Python + +```bash +#!/usr/bin/env python3 + +# g.parser demo script for python programming + +# %module +# % description: g.parser test script (python) +# % keyword: keyword1 +# % keyword: keyword2 +# %end +# %flag +# % key: f +# % description: A flag +# %end +# %option G_OPT_R_MAP +# % key: raster +# % required: yes +# %end +# %option G_OPT_V_MAP +# % key: vector +# %end +# %option +# % key: option1 +# % type: string +# % description: An option +# % required: no +# %end + +import os +import sys + +import grass.script as gs + +def main(): + flag_f = flags['f'] + option1 = options['option1'] + raster = options['raster'] + vector = options['vector'] + + #### add your code here #### + + if flag_f: + print "Flag -f set" + else: + print "Flag -f not set" + + # test if parameter present: + if option1: + print "Value of option1 option: '%s'" % option1 + + print "Value of raster option: '%s'" % raster + print "Value of vector option: '%s'" % vector + + #### end of your code #### + + return 0 + +if __name__ == "__main__": + options, flags = gs.parser() + sys.exit(main()) +``` + +### Example code for SHELL + +```bash +#!/bin/sh + +# g.parser demo script for shell programming + +# %module +# % description: g.parser test script (shell) +# %end +# %flag +# % key: f +# % description: A flag +# %end +# %option G_OPT_R_MAP +# % key: raster +# % required: yes +# %end +# %option G_OPT_V_MAP +# % key: vector +# %end +# %option +# % key: option1 +# % type: string +# % description: An option +# % required: no +# %end + +if [ -z "$GISBASE" ] ; then + echo "You must be in GRASS GIS to run this program." 1>&2 + exit 1 +fi + +if [ "$1" != "@ARGS_PARSED@" ] ; then + exec g.parser "$0" "$@" +fi + +#### add your code below #### + +echo "" + +if [ $GIS_FLAG_F -eq 1 ] ; then + g.message message="Flag -f set" +else + g.message message="Flag -f not set" +fi + +# test if parameter present: +if [ -n "$GIS_OPT_OPTION1" ] ; then + echo "Value of GIS_OPT_OPTION1: '$GIS_OPT_OPTION1'" +fi + +g.message message="Value of GIS_OPT_option1: '$GIS_OPT_option1'" +g.message message="Value of GIS_OPT_raster: '$GIS_OPT_raster'" +g.message message="Value of GIS_OPT_vect: '$GIS_OPT_vector'" + +#### end of your code #### +``` + +### Example code for Perl + +```bash +#!/usr/bin/perl -w +use strict; + +# g.parser demo script + +# %module +# % description: g.parser test script (perl) +# % keyword: keyword1 +# % keyword: keyword2 +# %end +# %flag +# % key: f +# % description: A flag +# %end +# %option G_OPT_R_MAP +# % key: raster +# % required: yes +# %end +# %option G_OPT_V_MAP +# % key: vector +# %end +# %option +# % key: option1 +# % type: string +# % description: An option +# % required: no +# %end + +if ( !$ENV{'GISBASE'} ) { + printf(STDERR "You must be in GRASS GIS to run this program.\n"); + exit 1; +} + +if( $ARGV[0] ne '@ARGS_PARSED@' ){ + my $arg = ""; + for (my $i=0; $i < @ARGV;$i++) { + $arg .= " $ARGV[$i] "; + } + system("$ENV{GISBASE}/bin/g.parser $0 $arg"); + exit; +} + +#### add your code here #### +print "\n"; +if ( $ENV{'GIS_FLAG_F'} eq "1" ){ + print "Flag -f set\n" +} +else { + print "Flag -f not set\n" +} + +printf ("Value of GIS_OPT_option1: '%s'\n", $ENV{'GIS_OPT_OPTION1'}); +printf ("Value of GIS_OPT_raster: '%s'\n", $ENV{'GIS_OPT_RASTER'}); +printf ("Value of GIS_OPT_vect: '%s'\n", $ENV{'GIS_OPT_VECTOR'}); + +#### end of your code #### +``` + +### Easy creation of a script + +By using the **--script** flag with any GRASS GIS module (must be run in +a GRASS GIS session) header, description, keywords, parameters, flags +and a template main Python script section will be printed in the +terminal which can be saved to a file and used for further script +programming. + +In this example, the module *v.what.rast* is used as an example. The +output is shown below: + +```bash +v.what.rast --script + +#!/usr/bin/env python3 +############################################################################ +# +# MODULE: v.what.rast_wrapper +# AUTHOR(S): username +# PURPOSE: Wrapper for v.what.rast +# COPYRIGHT: (C) 2017 by username, and the GRASS Development Team +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +############################################################################ + +# %module +# % description: Uploads raster values at positions of vector points to the table. +# % keyword: vector, sampling, raster, position, querying, attribute table, surface information +# %end +# %flag +# % key: i +# % description: Interpolate values from the nearest four cells +# %end +# %flag +# % key: p +# % description: Print categories and values instead of updating the database +# %end +# %option +# % key: map +# % type: string +# % required: yes +# % multiple: no +# % key_desc: name +# % label: Name of vector points map for which to edit attributes +# % description: Or data source for direct OGR access +# % gisprompt: old,vector,vector +# %end +# %option +# % key: layer +# % type: string +# % required: no +# % multiple: no +# % label: Layer number or name +# % description: Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name. +# % answer: 1 +# % gisprompt: old,layer,layer +# %end +# %option +# % key: type +# % type: string +# % required: no +# % multiple: yes +# % options: point,centroid +# % description: Input feature type +# % answer: point +# %end +# %option +# % key: raster +# % type: string +# % required: yes +# % multiple: no +# % key_desc: name +# % description: Name of existing raster map to be queried +# % gisprompt: old,cell,raster +# %end +# %option +# % key: column +# % type: string +# % required: no +# % multiple: no +# % key_desc: name +# % description: Name of attribute column to be updated with the query result +# % gisprompt: old,dbcolumn,dbcolumn +# %end +# %option +# % key: where +# % type: string +# % required: no +# % multiple: no +# % key_desc: sql_query +# % label: WHERE conditions of SQL statement without 'where' keyword +# % description: Example: income < 1000 and population >= 10000 +# %end + +import sys + +import grass.script as gs + +def main(): + # put code here + + return 0 + +if __name__ == "__main__": + options, flags = gs.parser() + sys.exit(main()) +``` + +## SEE ALSO + +*[g.filename](g.filename.md), [g.findfile](g.findfile.md), +[g.tempfile](g.tempfile.md)* + +Overview table: [Parser standard options](parser_standard_options.md) + +[Style Guide: Developing Python +scripts](https://github.com/OSGeo/grass/blob/main/doc/development/style_guide.md#developing-python-scripts) + +Related Wiki pages: [Using GRASS GIS with other programming +languages](https://grasswiki.osgeo.org/wiki/Category:Linking_to_other_languages) + +## AUTHOR + +Glynn Clements diff --git a/general/g.pnmcomp/g.pnmcomp.md b/general/g.pnmcomp/g.pnmcomp.md new file mode 100644 index 00000000000..45934e75fd2 --- /dev/null +++ b/general/g.pnmcomp/g.pnmcomp.md @@ -0,0 +1,36 @@ +## DESCRIPTION + +*g.pnmcomp* isn't meant for end users. It's an internal tool for use by +*[wxGUI](wxGUI.md)*. + +In essence, *g.pnmcomp* generates a PPM image by overlaying a series of +PPM/PGM pairs (PPM = RGB image, PGM = alpha channel). + +## NOTES + +The intention is that *d.\** modules will emit PPM/PGM pairs (by way of +the PNG-driver code being integrated into Display Library). The GUI will +manage a set of layers; each layer consists of the data necessary to +generate a PPM/PGM pair. Whenever the layer "stack" changes (by adding, +removing, hiding, showing or re-ordering layers), the GUI will render +any layers for which it doesn't already have the PPM/PGM pair, then +re-run *g.pnmcomp* to generate the final image (just redoing the +composition is a lot faster than redrawing everything). + +A C/C++ GUI would either have *g.pnmcomp's* functionality (image +composition) built-in, or would use the system's graphics API to perform +composition (for translucent layers, you would need OpenGL or the Render +extension, or something else which supports translucent rendering). + +Tk doesn't support transparent (masked) true-colour images (it does +support transparent GIFs, but that's limited to 256 colours), and an +image composition routine in Tcl would be unacceptably slow, hence the +existence of *g.pnmcomp*. + +## SEE ALSO + +*[g.cairocomp](g.cairocomp.md)* + +## AUTHOR + +Glynn Clements diff --git a/general/g.ppmtopng/g.ppmtopng.md b/general/g.ppmtopng/g.ppmtopng.md new file mode 100644 index 00000000000..9636ef68fd5 --- /dev/null +++ b/general/g.ppmtopng/g.ppmtopng.md @@ -0,0 +1,8 @@ +## DESCRIPTION + +*g.ppmtopng* isn't meant for end users. It's a utility to convert +between PPM/PGM and PNG image formats. + +## AUTHOR + +Glynn Clements diff --git a/general/g.proj/g.proj.md b/general/g.proj/g.proj.md new file mode 100644 index 00000000000..657b390814c --- /dev/null +++ b/general/g.proj/g.proj.md @@ -0,0 +1,246 @@ +## DESCRIPTION + +*g.proj* provides a means of converting a coordinate reference system +(CRS) description between various formats. + +For an introduction to map projections (with PROJ),see the manual page +of [r.proj](r.proj.md). + +If compiled without [OGR](https://gdal.org/) present, the functionality +is limited to: + +- Reporting the CRS information for the current project (previously + called location), either in conventional GRASS (**-p** flag) or PROJ + (**-j** flag) format +- Changing the datum, or reporting and modifying the datum + transformation parameters, for the current project + +When compiled with OGR, functionality is increased and allows output of +the CRS information in the Well-Known Text (WKT) format popularised by +proprietary GIS. In addition, if one of the parameters *georef*, *wkt*, +*proj4* or *epsg* is specified, rather than being read from the current +project, the CRS information is imported from an external source as +follows: + +georef=*filename* +*g.proj* attempts to invoke GDAL and OGR in turn to read a georeferenced +file *filename*. The CRS information will be read from this file. If the +file is not georeferenced or cannot be read, XY (unprojected) will be +used. + +wkt=*filename* or **-** +The file *filename* should contain a CRS description in WKT format with +or without line-breaks (e.g. a '.prj' file). If **-** is given for the +filename, the WKT description will be read from stdin rather than a +file. + +proj4=*description* or **-** +*description* should be a CRS description in [PROJ](https://proj.org/) +format, enclosed in quotation marks if there are any spaces. If **-** is +given for *description*, the PROJ description will be read from stdin +rather than as a directly-supplied command-line parameter. + +epsg=*number* +*number* should correspond to the index number of a valid co-ordinate +system in the [EPSG database](https://epsg.org/search/by-name). EPSG +code support is based upon a local copy of the GDAL CSV co-ordinate +system and datum information files, stored in the directory +`$GISBASE/etc/proj/ogr_csv`. These can be updated if necessary to +support future revisions of the EPSG database. + +If datum information is incorrect or missing in the input co-ordinate +system definition (e.g. PROJ descriptions have very limited support for +specifying datum names), a GRASS datum abbreviation can instead be +supplied using the *datum* parameter. This will override any datum +contained in the input co-ordinate system, and discard any datum +transformation parameters. Enter datum=*list* to return a list of all +the datums supported by GRASS. Since any existing datum transformation +parameters will have been discarded, the *datumtrans* parameter should +in general always be used in conjunction with *datum*. + +The **-p**, **-j**, **-w**, etc. flags are all functional when importing +CRS information from an external source, meaning that *g.proj* can be +used to convert between representations of the information. It is +**not** required that either the input or output be in GRASS format. + +In addition however, if the **-c** flag is specified, *g.proj* will +create new GRASS CRS files (PROJ_INFO, PROJ_UNITS, WIND and +DEFAULT_WIND) based on the imported information. If the *project* +parameter is specified in addition to **-c**, then a new project will be +created. Otherwise the CRS information files in the current project will +be overwritten. The program will **not** warn before doing this. + +The final mode of operation of *g.proj* is to report on the datum +information and datum transformation parameters associated with the +co-ordinate system. The **-d** flag will report a human-readable summary +of this. + +## NOTES + +If the input co-ordinate system contains a datum name but no +transformation parameters, and there is more than one suitable parameter +set available (according to the files datum.table and +datumtransform.table in `$GISBASE/etc/proj`), *g.proj* will check the +value of the *datumtrans* option and act according to the following: + +- **-1:** List available parameter sets in a GUI-parsable (but also + human-readable) format and exit. +- **0 (default):** Continue without specifying parameters - if used when + creating a project, other GRASS modules will use the "default" (likely + non-optimum) parameters for this datum if necessary in the future. +- **Any other number less than or equal to the number of parameter sets + available for this datum:** Choose this parameter set and add it to + the co-ordinate system description. + +If the **-t** flag is specified, the module will attempt to change the +datum transformation parameters using one of the above two methods +**even if** a valid parameter set is already specified in the input +co-ordinate system. This can be useful to change the datum information +for an existing project. + +Output is simply based on the input CRS information. g.proj does **not** +attempt to verify that the co-ordinate system thus described matches an +existing system in use in the world. In particular, this means there are +no EPSG Authority codes in the WKT output. + +WKT format shows the false eastings and northings in the projected unit +(e.g. meters, feet) but in PROJ format it should always be given in +meters. + +The maximum size of input WKT or PROJ CRS descriptions is limited to +8000 bytes. + +## EXAMPLES + +### Print information + +Print the CRS information for the current project: + +```bash +g.proj -p +``` + +List the possible datum transformation parameters for the current +project: + +```bash +g.proj -t datumtrans=-1 +``` + +### Create projection (PRJ) file + +Create a '.prj' file in ESRI format corresponding to the current +project: + +```bash +g.proj -wef > irish_grid.prj +``` + +### Read CRS from file + +Read the CRS information from a GeoTIFF file and print it in PROJ +format: + +```bash +g.proj -jf georef=ASTER_DEM20020508161837.tif +``` + +Convert the PROJ CRS description contained in a text file to WKT +format: + +```bash +cat proj4.description | g.proj -w proj4=- +``` + +### Create new project + +Create a new project with the coordinate system referred to by EPSG code +4326 (Latitude-Longitude/WGS84), without explicitly specifying datum +transformation parameters: + +```bash +g.proj -c epsg=4326 project=latlong +``` + +Create a new project with the coordinate system referred to by EPSG code +3857 ([Pseudo-Mercator +Projection](https://spatialreference.org/ref/epsg/3857/)) + +```bash +g.proj -c epsg=3857 project=google +``` + +Create a new project with the coordinate system referred to by EPSG code +29900 (Irish Grid), selecting datum transformation parameter set no. +2: + +```bash +# list available datums for EPSG code 29900 +g.proj -t datumtrans=-1 epsg=29900 +g.proj -c epsg=29900 datumtrans=2 project=irish_grid +``` + +Create a new project with the same coordinate system as the current +project, but forcing a change to datum transformation parameter set no. +1: + +```bash +g.proj -c project=newloc -t datumtrans=1 +``` + +Create a new project with the coordinate system from a WKT definition +stored in a text file: + +```bash +g.proj -c wkt=irish_grid.prj project=irish_grid +``` + +Create a new project from a PROJ description, explicitly specifying a +datum and using the default datum transformation parameters: + +```bash +g.proj -c project=spain proj4="+proj=utm +zone=30 +ellps=intl" datum=eur50 datumtrans=0 +``` + +### Using g.proj output for GDAL/OGR tools + +Reproject external raster map to current GRASS project (does not always +make sense!) using the GDAL 'gdalwarp' tool. We recommend to use the +ERDAS/Img format and not to use the ESRI style of WKT: + +```bash +# example for 30x30 pixel resolution (enforce with -tr to avoid odd values) +gdalwarp -of HFA -tr 30 30 -t_srs "`g.proj -wf`" aster.img aster_tmerc.img +``` + +Reproject external vector map to current GRASS project using the OGR +'ogr2ogr' tool: + +```bash +ogr2ogr -t_srs "`g.proj -wf`" polbnda_italy_GB_ovest.shp polbnda_italy_LL.shp +``` + +## REFERENCES + +[PROJ](https://proj.org): Projection/datum support library +[GDAL raster library and toolset](https://gdal.org) +[OGR vector library and toolset](https://gdal.org/) + +**Further reading** + +- [ASPRS Grids and + Datum](https://www.asprs.org/asprs-publications/grids-and-datums) +- [MapRef - The Collection of Map Projections and Reference Systems for + Europe](https://mapref.org) +- [Projections Transform List](http://geotiff.maptools.org/proj_list/) + (PROJ) + +## SEE ALSO + +*[m.proj](m.proj.md), [r.proj](r.proj.md), [v.proj](v.proj.md), +[r.import](r.import.md), [r.in.gdal](r.in.gdal.md), +[v.import](v.import.md), [v.in.ogr](v.in.ogr.md)* + +## AUTHOR + +Paul Kelly diff --git a/general/g.region/g.region.md b/general/g.region/g.region.md new file mode 100644 index 00000000000..6124016d761 --- /dev/null +++ b/general/g.region/g.region.md @@ -0,0 +1,403 @@ +## DESCRIPTION + +The *g.region* module allows the user to manage the settings of the +current geographic region. These regional boundaries can be set by the +user directly and/or set from a region definition file (stored under the +`windows` directory in the user's current mapset). The user can create, +modify, and store as many geographic region definitions as desired for +any given mapset. However, only one of these geographic region +definitions will be current at any given moment, for a specified mapset; +i.e., GRASS programs that respect the geographic region settings will +use the current geographic region settings. + +## DEFINITIONS + +**Region:** +In GRASS, a *region* refers to a geographic area with some defined +boundaries, based on a specific map coordinate system and map +projection. Each region also has associated with it the specific +east-west and north-south resolutions of its smallest units (rectangular +units called "cells"). + +The region's boundaries are given as the northernmost, southernmost, +easternmost, and westernmost points that define its extent (cell edges). +The north and south boundaries are commonly called *northings*, while +the east and west boundaries are called *eastings*. + +The region's cell resolution defines the size of the smallest piece of +data recognized (imported, analyzed, displayed, stored, etc.) by GRASS +modules affected by the current region settings. The north-south and +east-west cell resolutions need not be the same, thus allowing +non-square data cells to exist. + +Typically all raster and display modules are affected by the current +region settings, but not vector modules. Some special modules diverge +from this rule, for example raster import modules and *v.in.region*. + +**Default Region:** +Each GRASS project (previously called location) has a fixed geographic +region, called the default geographic region (stored in the region file +`DEFAULT_WIND` under the special mapset `PERMANENT`), that defines the +extent of the data base. While this provides a starting point for +defining new geographic regions, user-defined geographic regions need +not fall within this geographic region. The current region can be reset +to the default region with the **-d** flag. The default region is +initially set when the project is first created and can be reset using +the **-s** flag. + +**Current Region:** +Each mapset has a current geographic region. This region defines the +geographic area in which all GRASS displays and raster analyses will be +done. Raster data will be resampled, if necessary, to meet the cell +resolutions of the current geographic region setting. + +**Saved Regions:** +Each GRASS MAPSET may contain any number of pre-defined, and named, +geographic regions. These region definitions are stored in the user's +current mapset location under the `windows` directory (also referred to +as the user's saved region definitions). Any of these pre-defined +geographic regions may be selected, by name, to become the current +geographic region. Users may also access saved region definitions stored +under other mapsets in the current project, if these mapsets are +included in the user's mapset search path or the '@' operator is used +(`region_name@mapset`). + +## NOTES + +After all updates have been applied, the current region's southern and +western boundaries are (silently) adjusted so that the north/south +distance is a multiple of the north/south resolution and that the +east/west distance is a multiple of the east/west resolution. + +With the **-a** flag all four boundaries are adjusted to be even +multiples of the resolution, aligning the region to the resolution +supplied by the user. The default is to align the region resolution to +match the region boundaries. + +The **-m** flag will report the region resolution in meters. The +resolution is calculated by averaging the resolution at the region +boundaries. This resolution is calculated by dividing the geodesic +distance in meters at the boundary by the number of rows or columns. For +example the east / west resolution (ewres) is determined from an average +of the geodesic distances at the North and South boundaries divided by +the number of columns. + +The **-p** (or **-g**) option is recognized last. This means that all +changes are applied to the region settings before printing occurs. + +The **-g** flag prints the current region settings in shell script +style. This format can be given back to *g.region* on its command line. +This may also be used to save region settings as shell environment +variables with the UNIX eval command, "`` eval `g.region -g` ``". + +With **-u** flag current region is not updated even if one or more +options for changing region is used (**res=**, **raster=**, etc). This +can be used for example to print modified region values for further use +without actually modifying the current region. Similarly, **-o** flag +forces to update current region file even when e.g., only printing was +specified. Flag **-o** was added in GRASS GIS version 8 to simulate +*g.region* behavior in prior versions when current region file was +always updated unless **-u** was specified. + +### Additional parameter information + +**zoom=***name* +Shrink current region settings to the smallest region encompassing all +non-NULL data in the named raster map layer that fall inside the user's +current region. In this way you can tightly zoom in on isolated clumps +within a bigger map. + +If the user also includes the **raster=***name* option on the command +line, **zoom=***name* will set the current region settings to the +smallest region encompassing all non-NULL data in the named **zoom** map +that fall inside the region stated in the cell header for the named +**raster** map. + +**align=***name* +Set the current resolution equal to that of the named raster map, and +align the current region to a row and column edge in the named map. +Alignment only moves the existing region edges outward to the edges of +the next nearest cell in the named raster map - not to the named map's +edges. To perform the latter function, use the **raster=***name* option. + +## EXAMPLES + +### Printing extent and raster resolution in 2D and 3D + +` g.region -p ` +This will print the current region in the format: + +```bash +projection: 1 (UTM) +zone: 13 +datum: nad27 +ellipsoid: clark66 +north: 4928000 +south: 4914000 +west: 590000 +east: 609000 +nsres: 20 +ewres: 20 +rows: 700 +cols: 950 +``` + +` g.region -p3 ` +This will print the current region and the 3D region (used for voxels) +in the format: + +```bash +projection: 1 (UTM) +zone: 13 +datum: nad27 +ellipsoid: clark66 +north: 4928000 +south: 4914000 +west: 590000 +east: 609000 +top: 1.00000000 +bottom: 0.00000000 +nsres: 20 +nsres3: 20 +ewres: 20 +ewres3: 20 +tbres: 1 +rows: 700 +rows3: 700 +cols: 950 +cols3: 950 +depths: 1 +``` + +` g.region -g ` +The **-g** option prints the region in the following script style +(key=value) format: + +```bash +n=4928000 +s=4914000 +w=590000 +e=609000 +nsres=20 +ewres=20 +rows=700 +cols=950 +``` + +` g.region -bg ` +The **-bg** option prints the region in the following script style +(key=value) format plus the boundary box in latitude-longitude/WGS84: + +```bash +n=4928000 +s=4914000 +w=590000 +e=609000 +nsres=20 +ewres=20 +rows=700 +cols=950 +LL_W=-103.87080682 +LL_E=-103.62942884 +LL_N=44.50164277 +LL_S=44.37302019 +``` + +` g.region -l ` +The **-l** option prints the region in the following format: + +```bash +long: -103.86789484 lat: 44.50165890 (north/west corner) +long: -103.62895703 lat: 44.49904013 (north/east corner) +long: -103.63190061 lat: 44.37303558 (south/east corner) +long: -103.87032572 lat: 44.37564292 (south/west corner) +rows: 700 +cols: 950 +Center longitude: 103:44:59.170374W [-103.74977] +Center latitude: 44:26:14.439781N [44.43734] +``` + +` g.region -pm ` +This will print the current region in the format (latitude-longitude +project): + +```bash +projection: 3 (Latitude-Longitude) +zone: 0 +ellipsoid: wgs84 +north: 90N +south: 40N +west: 20W +east: 20E +nsres: 928.73944902 +ewres: 352.74269109 +rows: 6000 +cols: 4800 +``` + +Note that the resolution is here reported in meters, not decimal +degrees. + +### Changing extent and raster resolution using values + +` g.region n=7360100 e=699000 ` +will reset the northing and easting for the current region, but leave +the south edge, west edge, and the region cell resolutions unchanged. + +` g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01 ` +will reset the northing, easting, southing, westing and resolution for +the current region, here in DMS latitude-longitude style (decimal +degrees and degrees with decimal minutes can also be used). + +` g.region -dp s=698000 ` +will set the current region from the default region for the GRASS +project, reset the south edge to 698000, and then print the result. + +` g.region n=n+1000 w=w-500 ` +The n=*value* may also be specified as a function of its current value: +n=n+*value* increases the current northing, while n=n-*value* decreases +it. This is also true for s=*value*, e=*value*, and w=*value*. In this +example the current region's northern boundary is extended by 1000 units +and the current region's western boundary is decreased by 500 units. + +` g.region n=s+1000 e=w+1000 ` +This form allows the user to set the region boundary values relative to +one another. Here, the northern boundary coordinate is set equal to 1000 +units larger than the southern boundary's coordinate value, and the +eastern boundary's coordinate value is set equal to 1000 units larger +than the western boundary's coordinate value. The corresponding forms +s=n-*value* and + +w=e-*value* may be used to set the values of the region's southern and +western boundaries, relative to the northern and eastern boundary +values. + +### Changing extent and raster resolution using maps + +` g.region raster=soils ` +This form will make the current region settings exactly the same as +those given in the cell header file for the raster map layer *soils*. + +` g.region raster=soils zoom=soils ` +This form will first look up the cell header file for the raster map +layer *soils*, use this as the current region setting, and then shrink +the region down to the smallest region which still encompasses all +non-NULL data in the map layer *soils*. Note that if the parameter +*raster=soils* were not specified, the zoom would shrink to encompass +all non-NULL data values in the soils map that were located within the +*current region* settings. + +` g.region -up raster=soils ` +The **-u** option suppresses the re-setting of the current region +definition. This can be useful when it is desired to only extract region +information. In this case, the cell header file for the soils map layer +is printed without changing the current region settings. + +` g.region -up zoom=soils save=soils ` +This will zoom into the smallest region which encompasses all non-NULL +soils data values, and save the new region settings in a file to be +called *soils* and stored under the `windows` directory in the user's +current mapset. The current region settings are not changed. + +### Changing extent and raster resolution in 3D + +` g.region b=0 t=3000 tbres=200 res3=100 g.region -p3 ` +This will define the 3D region for voxel computations. In this example a +volume with bottom (0m) to top (3000m) at horizontal resolution (100m) +and vertical resolution (200m) is defined. + +### Using g.region in a shell in combination with OGR + +Extracting a spatial subset of the external vector map `soils.shp` into +new external vector map `soils_cut.shp` using the OGR *ogr2ogr* tool: + +```bash +eval `g.region -g` +ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp +``` + +This requires that the project and the SHAPE file CRS' match. + +### Using g.region in a shell in combination with GDAL + +Extracting a spatial subset of the external raster map +`p016r035_7t20020524_z17_nn30.tif` into new external raster map +`p016r035_7t20020524_nc_spm_wake_nn30.tif` using the GDAL *gdalwarp* +tool: + +```bash +eval `g.region -g` +gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \ + p016r035_7t20020524_z17_nn30.tif \ + p016r035_7t20020524_nc_spm_wake_nn30.tif +``` + +Here the input raster map does not have to match the project's +coordinate reference system since it is reprojected on the fly. + +### JSON Output + +```bash +g.region -p format=json +``` + +```bash +{ + "projection": "99 (Lambert Conformal Conic)", + "zone": 0, + "datum": "nad83", + "ellipsoid": "a=6378137 es=0.006694380022900787", + "region": { + "north": 320000, + "south": 10000, + "west": 120000, + "east": 935000, + "ns-res": 500, + "ns-res3": 1000, + "ew-res": 500, + "ew-res3": 1000 + }, + "top": 500, + "bottom": -500, + "tbres": 100, + "rows": 620, + "rows3": 310, + "cols": 1630, + "cols3": 815, + "depths": 10, + "cells": 1010600, + "cells3": 2526500 +} +``` + +```bash +g.region -l format=json +``` + +```bash +{ + "nw_long": -78.688888505507336, + "nw_lat": 35.743893244701788, + "ne_long": -78.669097826118957, + "ne_lat": 35.743841072010554, + "se_long": -78.669158624787542, + "se_lat": 35.728968779193615, + "sw_long": -78.688945667963168, + "sw_lat": 35.729020942542441, + "center_long": -78.679022655614958, + "center_lat": 35.736431420327719, + "rows": 165, + "cols": 179 +} +``` + +## SEE ALSO + +*[g.access](g.access.md), [g.mapsets](g.mapsets.md), +[g.proj](g.proj.md) +Environment variables: [GRASS_REGION and +WIND_OVERRIDE](variables.md#internal)* + +## AUTHOR + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory diff --git a/general/g.remove/g.remove.md b/general/g.remove/g.remove.md new file mode 100644 index 00000000000..2a55d31f4a5 --- /dev/null +++ b/general/g.remove/g.remove.md @@ -0,0 +1,37 @@ +## DESCRIPTION + +*g.remove* removes data files matching a pattern given by wildcards or +POSIX Extended Regular Expressions. If the **-f** force flag is not +given then nothing is removed, instead the list of selected file names +is printed to `stdout` as a preview of the files to be deleted. + +## EXAMPLES + +Delete `map1` and `map2` raster maps in the current mapset: + +```bash +g.remove -f type=raster name=tmp1,tmp2 +``` + +Delete all raster and vector maps starting with "`tmp_`" in the current +mapset: + +```bash +# show matching raster and vector maps but do not delete yet (as verification) +g.remove type=raster,vector pattern="tmp_*" + +# actually delete the matching raster and vector maps +g.remove -f type=raster,vector pattern="tmp_*" +``` + +Delete all vector maps starting with "`stream_`" in the current mapset, +but exclude those ending with "`_final`": + +```bash +g.remove -f type=vector pattern="stream_*" exclude="*_final" +``` + +## AUTHOR + +Huidae Cho + diff --git a/general/g.rename/g.rename.md b/general/g.rename/g.rename.md new file mode 100644 index 00000000000..4ea12c3cc30 --- /dev/null +++ b/general/g.rename/g.rename.md @@ -0,0 +1,60 @@ +## DESCRIPTION + +*g.rename* allows the user to rename data base element files in the +user's current mapset. The user can specify all necessary information to +*g.rename* on the command line, by specifying: the type of data base +element to be renamed (one or more of: **raster**, **raster_3d**, +**vector**, **icon**, **labels**, **region**, and **group**); the +specific file element in the current mapset to be renamed (*old*); and +the new name to be assigned to this file element (*new*) in the current +mapset. The file element *old* is then renamed to *new*. + +Users can also simply type *g.rename --help* without arguments on the +command line, to receive a menu of existing data base element types and +files from which to choose for possible renaming: + +```bash + raster raster map(s) to be renamed + raster_3d 3D raster map(s) to be renamed + vector vector map(s) to be renamed + labels paint label file(s) to be renamed + region region definition(s) to be renamed + group imagery group(s) to be renamed +``` + +## NOTES + +If a data base element has support files (e.g., as is commonly the case +with raster maps), these support files also are renamed. + +If the user attempts to rename a file to itself by setting the *new* +file name equal to the *old* file name (e.g., **g.rename +raster=soils,soils**), *g.rename* will not execute the rename, but +instead state that no rename is needed. However, *g.rename* will allow +the user to overwrite other existing files in the current mapset by +making the *new* file name that of an already existing file. + +For portability reasons, *g.rename* is ignoring case of names. To change +the case of a map name, first rename the map to a name which differs by +more than case, then rename it to the intended name. + +## EXAMPLE + +```bash +# rename raster map +g.rename raster=oldrast,newrast + +# rename vector map +g.rename vector=oldvect,newvect + +# combined renaming +g.rename raster=oldrast,newrast vector=oldvect,newvect +``` + +## SEE ALSO + +*[g.copy](g.copy.md), [g.list](g.list.md), [g.remove](g.remove.md)* + +## AUTHOR + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory diff --git a/general/g.setproj/g.setproj.md b/general/g.setproj/g.setproj.md new file mode 100644 index 00000000000..2f1b9651c0b --- /dev/null +++ b/general/g.setproj/g.setproj.md @@ -0,0 +1,78 @@ +![GRASS logo](grass_logo.png) + +------------------------------------------------------------------------ + +## NAME + +***g.setproj*** allows the user to create the PROJ_INFO and the +PROJ_UNITS files to record the coordinate reference system (CRS) +information associated with a current project (previously called +location). + +## SYNOPSIS + +**g.setproj** + +## DESCRIPTION + +Allows a user to create a PROJ_INFO file in the PERMANENT mapset of the +current project. PROJ_INFO file is used to record the CRS information +associated with the specified project. + +## NOTES + +The user running *g.setproj* must own the PERMANENT mapset and it must +be currently selected. It is highly recommended to run *g.setproj* after +creating a new project so that conversion programs (such as *v.proj*) +can be run. + +The user will be prompted for the projection name. Most projections are +supported. The [PROJ](https://proj.org/) abbreviations for the names are +used with two exceptions, viz. 'll', for latitude / longitude geographic +co-ordinates, and 'stp', for the State Plane Co-ordinate system (used in +the USA). + +After the projection name, the user will be asked for a geodetic datum. +If no datum transformation support is needed, the question may be +answered with no, and no datum will be specified in the PROJ_INFO file. +If this is the case the user must specify the ellipsoid (model of the +curvature of the earth) to be used, otherwise it is determined by the +datum being used. + +If the datum or ellipsoid required are not listed within this program, +the user/administrator may add the definition to the files datum.table, +datumtransform.table and ellipse.table in the `$GISBASE/etc/proj` +directory. + +Depending on the projection selected, the user will then be prompted for +the various other parameters required to define it. + +The projections of aea, lcc, merc, leae, leac, and tmerc will generate a +request to the user for the prime meridian and standard parallel for the +output map. + +## SEE ALSO + +*[g.proj](g.proj.md), [m.proj](m.proj.md), [r.proj](r.proj.md), +[v.proj](v.proj.md), [PROJ](https://proj.org) site* + +**Further reading** + +- A guide to [Map + Projections](https://web.archive.org/web/20080513234144/http://erg.usgs.gov/isb/pubs/MapProjections/projections.html) + by USGS +- [ASPRS Grids and + Datum](https://www.asprs.org/asprs-publications/grids-and-datums) +- [MapRef - The Collection of Map Projections and Reference Systems for + Europe](https://mapref.org) +- [Projections Transform List](http://geotiff.maptools.org/proj_list/) + (PROJ) + +## AUTHORS + +Irina Kosinovsky, U.S. Army Construction Engineering Research +Laboratory +Morten Hulden, morten at untamo.net - rewrote module and added 121 +projections +Andreas Lange, andreas.lange at rhein-main.de - added prelimnary map +datum support diff --git a/general/g.tempfile/g.tempfile.md b/general/g.tempfile/g.tempfile.md new file mode 100644 index 00000000000..c953ef83231 --- /dev/null +++ b/general/g.tempfile/g.tempfile.md @@ -0,0 +1,44 @@ +## DESCRIPTION + +*g.tempfile* is designed for shell scripts that need to use large +temporary files. GRASS provides a mechanism for temporary files that +does not depend on `/tmp/`. GRASS temporary files are created in the +data base with the assumption that there will be enough space under the +data base for large files. GRASS periodically removes temporary files +that have been left behind by programs that failed to remove them before +terminating. + +*g.tempfile* creates an unique file and prints the name. The user is +required to provide a process-id which will be used as part of the name +of the file. Most Unix shells provide a way to get the process id of the +current shell. For `/bin/sh` and `/bin/csh` this is `$$`. It is +recommended that `$$` be specified as the process-id for *g.tempfile*. + +## EXAMPLE + +For `/bin/sh` scripts the following syntax should be used: + +```bash +temp1=`g.tempfile pid=$$` +temp2=`g.tempfile pid=$$` +``` + +For `/bin/csh` scripts, the following can be used: + +```bash +set temp1=`g.tempfile pid=$$` +set temp2=`g.tempfile pid=$$` +``` + +## NOTES + +Each call to *g.tempfile* creates a different (i.e. unique) name. +Although GRASS does eventually get around to removing tempfiles that +have been left behind, the programmer should make every effort to remove +these files. They often get large and take up disk space. If you write +`/bin/sh` scripts, learn to use the +`/bin/sh`` related ``trap`` command. If you write ``/bin/csh`` scripts, learn to use the ``/bin/csh`` related ``onintr`` command.` + +## AUTHOR + +Michael Shapiro, U.S. Army Construction Engineering Research Laboratory diff --git a/general/g.version/g.version.md b/general/g.version/g.version.md new file mode 100644 index 00000000000..01294945373 --- /dev/null +++ b/general/g.version/g.version.md @@ -0,0 +1,87 @@ +## DESCRIPTION + +*g.version* prints to standard output the GRASS version number, date, +the GRASS GIS copyright (**-c** flag), and GRASS build information +(**-b** flag). + +## NOTES + +This program requires no command line arguments; the user simply types +*g.version* on the command line to see the version number and date of +the GRASS GIS software currently being run by the user. + +Information about GRASS GIS core [GIS +Library](https://grass.osgeo.org/programming8/gislib.html) can be +printed by **-r** flag. + +Version numbers of additional libraries like [PROJ](https://proj.org/), +[GDAL/OGR](https://gdal.org/) or [GEOS](https://trac.osgeo.org/geos) are +printed by **-e** flag. + +See also function `version()` from [Python Scripting +Library](https://grasswiki.osgeo.org/wiki/GRASS_Python_Scripting_Library). + +```bash +import grass.script as gcore + +print gcore.version() +``` + +## EXAMPLES + +### Basic info + +```bash +g.version + +GRASS 8.4.0 (2024) +``` + +### GIS Library info + +```bash +g.version -r + +GRASS 8.4.0 (2024) +libgis revision: c9e8576cf +libgis date: 2024-04-27T09:38:49+00:00 +``` + +### Full info in shell script style + +```bash +g.version -rge + +version=8.4.0 +date=2024 +revision=d57f40906 +build_date=2024-05-23 +build_platform=x86_64-pc-linux-gnu +build_off_t_size=8 +libgis_revision=c9e8576cf +libgis_date=2024-04-27T09:38:49+00:00 +proj=8.2.1 +gdal=3.4.3 +geos=3.9.2 +sqlite=3.36.0 +``` + +Note: if `revision=exported` is reported instead of the git hash then +the `git` program was not available during compilation of GRASS GIS and +the source code did not contain the `.git/` subdirectory (requires e.g. +to `git clone` the GRASS GIS [software +repository](https://github.com/OSGeo/grass/).) + +## Citing GRASS GIS + +The GRASS Development Team has invested significant time and effort in +creating GRASS GIS, please cite it when using it for data analysis. The +GRASS GIS [Web site](https://grass.osgeo.org/about/license/) offers +citations in different styles. + +## AUTHORS + +Michael Shapiro, U.S. Army Construction Engineering Research +Laboratory +Extended info by Martin Landa, Czech Technical University in Prague, +Czech Republic diff --git a/gui/wxguiintro.md b/gui/wxguiintro.md new file mode 100644 index 00000000000..c46f9a55987 --- /dev/null +++ b/gui/wxguiintro.md @@ -0,0 +1,62 @@ +### Introduction to the GRASS GIS Graphical User Interface + +#### Overview + +The wxGUI (wxPython-based Graphical User Interface) is the primary user +interface for GRASS GIS. Designed for efficiency and ease of use, the +wxGUI provides an intuitive way to interact with spatial data and the +powerful tools available in GRASS GIS. The GUI supports the +visualisation of spatial data, the execution of geoprocessing tasks or +the management of complex workflows and offers a comprehensive set of +tools. + +#### Features + +The wxGUI is designed to cater to both novice and advanced users with +the following features: + +- A clean and customizable layout for efficient workspace management. +- Integrated support for both raster and vector data operations. +- Drag-and-drop capabilities for quick layer addition and arrangement. +- Support for live previews of data and processing results. +- Direct access to GRASS GIS modules, complete with user-friendly dialog + windows. +- Advanced debugging and scripting capabilities for developers and power + users. + +#### Getting Started + +To launch the wxGUI, simply start GRASS GIS. Upon startup, the wxGUI +will load, providing access to its various components. The wxGUI usage +is explained in greater detail [here](wxGUI.md). New GRASS GIS users can +explore the integrated help system or visit the [GRASS GIS +documentation](https://grass.osgeo.org/documentation/) for tutorials and +guides. + +#### Key Components + +The wxGUI is composed of several modules and features: + +- **Map Display**: Visualize raster, vector, and 3D data layers in an + interactive map viewer. +- **Layer Manager**: Organize and control the visibility, styling, and + properties of your data layers. +- **Data Catalog**: Explore and manage GRASS GIS mapsets and spatial + data with ease. +- **Geoprocessing Tools**: Access a wide range of geospatial analysis + and modeling tools through an easy-to-use interface. +- **Command Console**: Run GRASS GIS commands directly, with syntax + highlighting and autocompletion support. +- **3D View**: Analyze and visualize 3D landscapes using NVIZ. + +The wxGUI components are explained in greater detail +[here](wxGUI.components.md). + +### See also + +- [Introduction to raster data processing](rasterintro.md) +- [Introduction to 3D raster data (voxel) processing](raster3dintro.md) +- [Introduction to image processing](imageryintro.md) +- [Introduction into temporal data processing](temporalintro.md) +- [Introduction to database management](databaseintro.md) +- [Projections and spatial transformations](projectionintro.md) diff --git a/gui/wxpython/animation/g.gui.animation.md b/gui/wxpython/animation/g.gui.animation.md new file mode 100644 index 00000000000..c43b6fca39d --- /dev/null +++ b/gui/wxpython/animation/g.gui.animation.md @@ -0,0 +1,89 @@ +## DESCRIPTION + +The **Animation Tool** is a *[wxGUI](wxGUI.md)* component for animating +series of GRASS raster or vector maps or space time datasets (created by +t.\* modules). + +Animation Tool allows you to: + +- display up to 4 synchronized animations +- each animation can consist of base map layer(s) and (multiple) series + in arbitrary order (for example, raising water level with elevation) +- control the animation speed +- interactively change active frame using a slider +- visualize space time datasets with unequally spaced intervals +- animate 3d view (partially implemented, not supported on Windows) +- export animation as a series of images, animated GIF, AVI or SWF +- choose format of time labels in case of animating maps with absolute + time +- choose background color +- set starting and ending region in order to change region during + animation (alternatively you can set N-S/E-W values instead of the + ending region; these are used for making the region smaller or larger + for each step) + +3D view animation enables to animate raster (as an elevation map or a +color map) or vector map (points, lines). Internally, module +*[m.nviz.image](m.nviz.image.md)* is used. To display 3D view animation +follow these steps: + +- open GRASS GUI, load maps and start 3D view +- set view, light and other parameters as you like +- save workspace file +- add new animation in Animation Tool, choose 3D view mode +- choose data (series of maps or space time dataset) used for animation +- set workspace file +- choose parameter (parameter of *[m.nviz.image](m.nviz.image.md)*) to + animate (e.g. color_map) + + + +## NOTE + +The Animation Tool follows the computational region settings, so please +be sure your computational region is set to the geographic extent of +maps you are animating. You can change the computational region (using +*[g.region](g.region.md)*) and then reload the maps to update the +animation. + +## EXAMPLES + +```bash +g.gui.animation raster=rmap1,rmap2,rmap3 + +g.gui.animation vector=vmap1,vmap2,vmap3 + +g.gui.animation strds=precipitation_2000_2010 +``` + +The loading of a series of maps into the Animation Tool can be +simplified with *[g.list](g.list.md)* (back ticks syntax works for Linux +and Mac only): + +```bash +g.gui.animation raster=`g.list type=raster mapset=. separator=comma pattern="precip*"` +``` + +Using extended regular expressions, the list of a series of raster maps +can be subset by e.g., numeric range (here: precipitation for the years +1997-2012): + +```bash +g.gui.animation raster=`g.list -e type=raster mapset=. separator=comma pattern="precip_total.(199[7-9]|200[0-9]|201[0-2]).sum"` +``` + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +*[g.gui.timeline](g.gui.timeline.md), [g.list](g.list.md), +[m.nviz.image](m.nviz.image.md)* + +See also related [wiki +page](https://grasswiki.osgeo.org/wiki/WxGUI_Animation_Tool). + +## AUTHOR + +Anna Kratochvilova, [Czech Technical University in +Prague](https://www.cvut.cz), Czech Republic diff --git a/gui/wxpython/datacatalog/g.gui.datacatalog.md b/gui/wxpython/datacatalog/g.gui.datacatalog.md new file mode 100644 index 00000000000..7724192e8d9 --- /dev/null +++ b/gui/wxpython/datacatalog/g.gui.datacatalog.md @@ -0,0 +1,48 @@ +## DESCRIPTION + +The **Data Catalog** is a *[wxGUI](wxGUI.md)* component for browsing, +modifying and managing GRASS maps. + +Data Catalog allows you to: + +- browse GRASS projects and mapsets in the current GIS directory +- browse GRASS 2D/3D raster and vector maps +- rename, copy, move and delete GRASS maps including reprojection + between different projects +- drag and drop maps for copying and moving +- searching and filtering maps using regular expressions +- display map in current project +- show metadata of maps + +Note that projects are called *locations* at some places and in old +documentation. + + +Figure: Data Catalog integrated in wxGUI. + +## NOTES + +Some operations (copying, renaming, deleting) are by default enabled +only within the current mapset. To allow changing data outside of your +current mapset, you need to press *Unlock* button in Data Catalog +toolbar. + +### WARNING + +When renaming, copying or deleting maps outside of Data Catalog, you +need to reload the current mapset or entire database, because it is +currently not synchronized. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +*[g.copy](g.copy.md), [g.rename](g.rename.md), [g.remove](g.remove.md), +[g.list](g.list.md)* + +## AUTHORS + +Anna Petrasova, NCSU GeoForAll Laboratory +Tereza Fiedlerova, OSGeoREL, Czech Technical University in Prague, Czech +Republic diff --git a/gui/wxpython/dbmgr/g.gui.dbmgr.md b/gui/wxpython/dbmgr/g.gui.dbmgr.md new file mode 100644 index 00000000000..a7b5a9e3a4f --- /dev/null +++ b/gui/wxpython/dbmgr/g.gui.dbmgr.md @@ -0,0 +1,55 @@ +## DESCRIPTION + +The **Attribute Table Manager** is a *[wxGUI](wxGUI.md)* component to +query, edit, and manage attribute data for vector maps. The attribute +table manager can be launched by clicking on icon +![icon](icons/table.png) in the toolbar. It's also available as a +stand-alone module *g.gui.dbmgr*. + +*Attribute table manager* allows you to: + +- browse attribute data of vector map, perform SQL select statements; +- modify attribute data, insert new records to attribute table, delete + existing records; +- highlight selected items in the Map Display Window; +- extract selected items into a new vector map; +- modify attribute table - add, drop, rename columns; +- modify vector map DB connection settings - add, remove or modify + layers. + +[](dbmgr_frame.png) +*Figure: Simple attribute filtering using Attribute Table Manager.* + +### SQL Builder + +[](dbmgr_sql_builder.png) +*Figure: Attribute filtering using Attribute Table Manager and SQL +Builder.* + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +*[db.columns](db.columns.md), [db.connect](db.connect.md), +[db.describe](db.describe.md), [db.drivers](db.drivers.md), +[db.execute](db.execute.md), [db.select](db.select.md), +[db.tables](db.tables.md)* + +*[v.db.addcolumn](v.db.addcolumn.md), [v.db.connect](v.db.connect.md), +[v.db.dropcolumn](v.db.dropcolumn.md), +[v.db.renamecolumn](v.db.renamecolumn.md), [v.what](v.what.md)* + +See also +[wiki](https://grasswiki.osgeo.org/wiki/WxGUI_Attribute_Table_Manager) +page including [video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI_Attribute_Table_Manager#Video_tutorials). + +## AUTHORS + +Martin Landa, [FBK-irst](https://www.fbk.eu) (2007-2008), Trento, Italy, +and OSGeoREL at the Czech Technical University in Prague, Czech +Republic +Michael Barton, Arizona State University, USA +Jachym Cepicky diff --git a/gui/wxpython/docs/wxGUI.components.md b/gui/wxpython/docs/wxGUI.components.md new file mode 100644 index 00000000000..176c209886b --- /dev/null +++ b/gui/wxpython/docs/wxGUI.components.md @@ -0,0 +1,42 @@ +## KEYWORDS + +[general](general.md), [GUI](topic_GUI.md) + +## DESCRIPTION + +List of available *[wxGUI](wxGUI.md)* components: + +- [Module dialogs](wxGUI.modules.md) +- [3D Viewer](wxGUI.nviz.md) (nviz) +- [Animation tool](wxGUI.animation.md), available as a command line tool + *[g.gui.animation](g.gui.animation.md)* +- [Attribute Table Manager](wxGUI.dbmgr.md), available also as a command + line tool *[g.gui.dbmgr](g.gui.dbmgr.md)* +- [Cartographic Composer](wxGUI.psmap.md), available also as a command + line tool *[g.gui.psmap](g.gui.psmap.md)* +- [Data Catalog](wxGUI.datacatalog.md), available also as a command line + tool *[g.gui.datacatalog](g.gui.datacatalog.md)* +- [Graphical Modeler](wxGUI.gmodeler.md), available also as a command + line tool *[g.gui.gmodeler](g.gui.gmodeler.md)* +- [Ground Control Points Manager](wxGUI.gcp.md), available also as a + command line tool *[g.gui.gcp](g.gui.gcp.md)* +- [Interactive Scatter Plot Tool](wxGUI.iscatt.md) +- [Map Swipe](wxGUI.mapswipe.md), available also as a command line tool + *[g.gui.mapswipe](g.gui.mapswipe.md)* +- [Supervised Classification Tool](wxGUI.iclass.md), available also as a + command line tool *[g.gui.iclass](g.gui.iclass.md)* +- Configuration tool for r.li modules, + *[g.gui.rlisetup](g.gui.rlisetup.md)* +- [Timeline Tool](wxGUI.timeline.md), available also as a command line + tool *[g.gui.timeline](g.gui.timeline.md)* +- [Temporal Plot Tool](wxGUI.tplot.md), available also as a command line + tool *[g.gui.tplot](g.gui.tplot.md)* +- [Vector Digitizer](wxGUI.vdigit.md), available also as a command line + tool *[g.gui.vdigit](g.gui.vdigit.md)* +- [Raster Digitizer](wxGUI.rdigit.md) available also as a command line + tool *[g.gui.rdigit](g.gui.rdigit.md)* +- [Vector Network Analysis Tool](wxGUI.vnet.md) + +## SEE ALSO + +*[wxGUI](wxGUI.md)* diff --git a/gui/wxpython/docs/wxGUI.iscatt.md b/gui/wxpython/docs/wxGUI.iscatt.md new file mode 100644 index 00000000000..b8620351d78 --- /dev/null +++ b/gui/wxpython/docs/wxGUI.iscatt.md @@ -0,0 +1,77 @@ +## KEYWORDS + +[display](display.md), [GUI](topic_GUI.md), +[imagery](keywords.md#imagery), [scatterplot](keywords.md#scatterplot), +[plot](keywords.md#plot) + +## DESCRIPTION + +**Interactive Scatter Plot Tool** allows analyzing group of raster maps. +The tool is integrated into *[Supervised Classification +Tool](wxGUI.iclass.md)* (see the screen shot below). Also it is possible +to launch it from Map Display Window +(`Analyze map → Interactive Scatter Plot Tool`). The main idea of the +tool is that everything is linked together (scatter plots together and +mapwindow with the scatter plots). The main feature of the tool is the +interactivity, which allows user to: + +- work with multiple plots, which represents multiple raster bands + combinations, +- highlight plotted points in open scatter plots according to currently + chosen pixels for classes by it's training areas (supported only in + *Supervised Classification Tool*), +- be able to define areas in plots and the tool will highlight pixels in + map display window and corresponding points in other plots, +- plot of confidence ellipses. + +## TOOL CONTROLS LAYOUT + + + +If editing mode is activated (the green polygon tool in toolbar), the +areas which were selected in the scatter plots are highlighted. In the +image you can see this area for scatter plot of bands `B_6, B_7` inside +the ellipse. Opacity and color of the selected area can be set in +settings. The area corresponds to the active class (in this case +clouds). Selected areas are subset of areas, which belongs to the +category. + +In the editing mode it is possible to select certain area by the +polygon, which can be created and edited by tools in editing toolbar. +After the area is selected, we can include or exclude it into active +category by clicking on the first (plus) respectively second (minus) +tool in the editing toolbar. In mapwindow corresponding pixels are shown +by the class raster representing selected areas in scatter plots. In +this case we can see clouds class raster (blue), forest class raster +(green) and water class raster (red). + +## NOTES + +The tool can analyze only integer (CELL) rasters. It works with 8 bit +range smoothly. The tool is capable of processing data up to 12 bit +range, however it is not recommended open many scatter plots in 12/11 +bit mode. It could require significant amount of memory and plot +rendering time can be longer. Analyzing of raster data with higher range +is not recommended. The raster range can be lowered using +*[r.rescale](r.rescale.md)*. + +## KNOWN ISSUES + +Selection of areas in mapwindow is currently supported only if the tool +was launched from *[Supervised Classification Tool](wxGUI.iclass.md)*. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md), +[r.rescale](r.rescale.md)* + +See also the user +[wiki](https://grasswiki.osgeo.org/wiki/WxGUI_Interactive_Scatter_Plot_Tool) +page. + +## AUTHOR + +Stepan Turek, [Google Summer of Code +2013](https://grasswiki.osgeo.org/wiki/GRASS_GSoC_2013_GRASS_GIS_Interactive_Scatter_Plot_Tool) +(mentor: Martin Landa) diff --git a/gui/wxpython/docs/wxGUI.md b/gui/wxpython/docs/wxGUI.md new file mode 100644 index 00000000000..35449d0de0f --- /dev/null +++ b/gui/wxpython/docs/wxGUI.md @@ -0,0 +1,598 @@ +## DESCRIPTION + +**wxGUI** is a native *Graphical User Interface* (GUI) for GRASS GIS. +Its main features include displaying geographical data in 2D and 3D, +calling GRASS GIS modules, and interacting with data. + +### Overview + +The GUI is composed of *three* main components: + +- The **Layer Manager** includes map layer management, integrated + command-line prompt, and command output window tab. +- The **Map Display Window** integrates basic tools for zooming, + panning, data querying, and map elements (north arrows, barscale, + etc.). Each display window is associated with its own set of map + layers in the layer manager. The user may start multiple map displays + during a session. The map layers for each display are grouped under + different tabs in the Layer Manager. +- [Module dialogs](wxGUI.modules.md) enable running GRASS modules that + can be searched and launched via Tools tab. + +### Layer Manager + +The *Layer Manager* provides an interactive graphical interface for +creating and managing GRASS displays. There is a toolbar to manage +displayed map layers, a layer tree frame in which map layers for display +are organized, a command output window tab, and interactive command line +prompt. On Linux and Windows platforms, the layer manager also has a +menu bar with a set of pull-down menus for all GRASS GIS functions +(analysis, file I/O, GIS configuration and management); on a Mac, the +GRASS functions menu is at the top of the screen. + +screenshot + +Figure: Layer Manager screenshot on Ubuntu + +The top left button of the toolbar opens a new *Map Display Window*. +Each map display has a unique set of layers to display and region +settings. Other toolbar buttons add layers of different types for +display in the selected map display window. There are additional buttons +for saving or opening workspace file, and others. + +Map layers are listed in the window frame below the toolbar. Layers can +include raster and vector maps, vector labels, and commands (where any +GRASS command can be written). Layers are displayed as arranged in the +layer tree: the bottom layer is displayed first and the top layer is +displayed last, as if the layers were a series of stacked overlays. + +The check box to the left of each layer makes it active or inactive for +display. Only active layers are displayed/redisplayed when the display +button is pressed. Layers can be organized into groups; entire groups +can be activated or deactivated for display. Layer tree composition can +be saved to a workspace file and opened in subsequent sessions, +restoring all layers and their display options. + +A right mouse click on a layer or left clicking the button to the right +of the layer opens a dropdown menu with options to remove or rename the +layer (not the actual map), change its display properties (d.rast and +d.vect options such as color, symbol, etc.), show its metadata (r.info, +v.info) or attributes, if applicable. + +A left mouse double click on a layer opens GUI for its display options +These options are those for the d.\* command for each layer type +(d.rast, d.vect, or d.grid, for example). + +#### Layer Manager Toolbar + +![icon](icons/monitor-create.png)  *Start new map display* +Opens a new map display and creates empty layer tree tab in Layer +Manager. + +![icon](icons/create.png)  *Create new workspace* +Removes all layers from the layer tree and creates a new, empty tree +where new layers can be added. + +![icon](icons/open.png)  *Open existing workspace file* +Opens an previously saved workspace file, containing a set of display +layers and their option settings. + +![icon](icons/save.png)  *Save current workspace to file* +Saves current set of layers and their options to a workspace file. + +![icon](icons/layer-open.png)  *Load map layers into workspace* +Loads selected raster or vector maps into current layer tree. + +![icon](icons/layer-raster-add.png)  *Add raster map layer* +Adds raster map to layer tree, see *[d.rast](d.rast.md)*. + +![icon](icons/layer-raster-more.png)  *Add various raster map layers (RGB, HIS, shaded relief...)* +Opens a dropdown menu that allows user to select to: + +![icon](icons/layer-raster3d-add.png)  *Add 3D raster map layer* +Adds 3D raster map to layer tree. + +![icon](icons/layer-rgb-add.png)  *Add RGB raster layer* +Combines and displays three raster maps defined as red, green, and blue +channels to create an RGB color map, see *[d.rgb](d.rgb.md)*. + +![icon](icons/layer-his-add.png)  *Add HIS raster layer* +Combines and displays two or three raster maps defined as hue, +intensity, and (optionally) saturation channels to create a color map, +see *[d.his](d.his.md)*. + +![icon](icons/layer-shaded-relief-add.png)  *Add shaded relief raster map layer* +Adds shaded relief raster map layer, see *[r.relief](r.relief.md)* and +*[d.shade](d.shade.md)*. + +![icon](icons/layer-aspect-arrow-add.png)  *Add raster arrows layer* +Adds map of raster cells with directional arrows drawn. Arrow direction +and length are determined by separate aspect/directional map and +(optional) slope/intensity map, see *[d.rast.arrow](d.rast.arrow.md)*. + +![icon](icons/layer-cell-cats-add.png)  *Add raster numbers layer* +Adds map of raster cells with numbers representing the cell values, see +*[d.rast.num](d.rast.num.md)*. + +![icon](icons/layer-vector-add.png)  *Add vector map layer* +Adds a vector map layer, see *[d.vect](d.vect.md)*. + +![icon](icons/layer-vector-more.png)  *Add various vector map layers (thematic, chart...)* +Opens a dropdown menu that allows user to select to: + +![icon](icons/layer-vector-thematic-add.png)  *Add thematic area (choropleth) map layer (for all vector types)* +Adds layer for thematic display values from a numeric attribute column +associated with a vector map. Options include: thematic display type +(graduated colors or point sizes), methods for creating display +intervals, SQL query of attribute column to limit vector objects to +display, control of point icon types and sizes, control of thematic +color schemes, creation of legend for thematic map, and saving the +results of thematic mapping to a ps.map instructions file for later +printing, see *[d.vect.thematic](d.vect.thematic.md)*. + +![icon](icons/layer-vector-chart-add.png)  *Add thematic chart layer (for vector points)* +Adds layer in which pie or bar charts can be automatically created at +vector point locations. Charts display values from selected columns in +the associated attribute table. Options include: chart type, layer and +attributes to chart, chart colors, and chart size (fixed or based on +attribute column), see *[d.vect.chart](d.vect.chart.md)*. + +![icon](icons/layer-group-add.png)  *Add group* +Adds an empty group. Layers can then be added to the group. + +![icon](icons/layer-more.png)  *Add grid or vector labels overlay* +Opens a dropdown menu that allows user to select to: + +![icon](icons/layer-grid-add.png)  *Add overlay grids and lines* +Adds layer to display regular grid see *[d.grid](d.grid.md)* + +![icon](icons/layer-label-add.png)  *Add labels layer for vector objects (from existing labels file)* +Add a layer of text from a labels file for vector objects created with +the *[v.label](v.label.md)* module. A labels file can also be created +with a text editor, see *[d.labels](d.labels.md)*. + +![icon](icons/shortest-distance.png)  *Add geodesic line layer* +Add layer to display geodesic line for latitude/longitude projects only, +see *[d.geodesic](d.geodesic.md)* + +![icon](icons/shortest-distance.png)  *Add rhumbline layer* +Add layer to display rhumblines (for latitude/longitude projects only), +see *[d.rhumbline](d.rhumbline.md)*. + +![icon](icons/layer-command-add.png)  *Add command layer* +Adds a layer in which a GRASS GIS command or command list can be +entered. For a command list use the semi-colon (";") symbol as a +separator. For example: + +```bash +d.rast soils;d.rast -o roads;d.vect streams col=blue +``` + +Note that when an option of the command contains spaces, you need to +"escape" them with the backslash ('\\) character, for example: + +```bash +d.text text=Population\ density +``` + +![icon](icons/layer-remove.png)  *Delete selected layer* +Removes selected map layer or map layer group from layer tree. + +![icon](icons/edit.png)  *Edit vector maps* +Opens *[vector digitizer](wxGUI.vdigit.md)* to allow editing selected +vector map. + +![icon](icons/table.png)  *Show attribute table* +Opens *[attribute table manager](wxGUI.dbmgr.md)* for selected vector +map. + +![icon](icons/layer-open.png)  *Import raster or vector data* +![icon](icons/layer-import.png)  *Import raster data* +Import selected raster data into GRASS using *[r.in.gdal](r.in.gdal.md)* +and load them into current layer tree. + +![icon](icons/layer-import.png)  *Link external raster data* +Link selected external raster data as GRASS raster maps (using +*[r.external](r.external.md)*) and load them into current layer tree. + +![icon](icons/layer-export.png)  *Set raster output format* +Define external format for newly created raster maps (see +*[r.external.out](r.external.out.md)* for details) + +![icon](icons/layer-import.png)  *Import vector data* +Import selected vector data into GRASS using *[v.in.ogr](v.in.ogr.md)* +and load them into current layer tree. + +![icon](icons/layer-import.png)  *Link external vector data* +Link selected external vector data as GRASS vector maps (using +*[v.external](v.external.md)*) and load them into current layer tree. + +![icon](icons/layer-export.png)  *Set vector output format* +Define external format for newly created vector maps (see +*[v.external.out](v.external.out.md)* for details) + +![icon](icons/raster-calculator.png)  *Raster Map Calculator* +Launches Raster Calculator GUI front-end for +*[r.mapcalc](r.mapcalc.md)*. + +![icon](icons/modeler-main.png)  *Graphical Modeler* +Launches *[graphical modeler](wxGUI.gmodeler.md)* to create models and +run them. + +![icon](icons/georectify.png)  *Georectifier Tool* +Launches *[GCP Manager](wxGUI.gcp.md)* to create, edit, and manage +Ground Control Points. + +![icon](icons/print-compose.png)  *Cartographic Composer* +Launches *[Cartographic Composer](wxGUI.psmap.md)* to create +interactively hardcopy map outputs. + +![icon](icons/settings.png)  *Show GUI settings* +Opens dialog to change GUI settings. + +![icon](icons/help.png)  *Show help* +Opens GRASS manual. + +### Map Display Window + +The map display window includes toolbar that can be docked and undocked +from the window, a map canvas where a map composition of one or more +layers is displayed, and a statusbar with information about the +geographic region of the maps displayed. + +![Map Display Window](wxGUI_map_display.jpg) + +Figure: Map Display screenshot on Ubuntu + +Each Map Display Window has a unique layer tree (in the layer manager) +and geographic *region* setting. At the top of the window is a toolbar +with buttons to manage the map in the display (render, erase, zoom and +pan), for query and and analysis (distance measurement, profile, and +histogram creation), to overlay map elements onto the display (scale, +north arrow, legend, and custom text), and to export or print the +display. + +In the statusbar, the user can choose to display the geographic +coordinates under the cursor, current geographical region extent, +computational region (including graphical visualization in map display), +map display geometry (number of rows, columns, resolution) and map +scale. Checking the *render* button in the statusbar will cause the map +display to update automatically any time a map is added to, removed +from, or changed in its layer tree. + +It is important to note that zooming in any display will have *no* +effect on the 'computational region' setting (set with +*[g.region](g.region.md)*). Only by selecting the 'Set current region to +match display' item in the zoom menu (in the map display toolbar) will +the current display extents be copied to the computational region +extents. + +#### Map Display Toolbar + +![icon](icons/layer-redraw.png)  *Re-render display* +Re-renders all active map layers regardless of whether they have changed +or not, see *[d.redraw](d.redraw.md)*. + +![icon](icons/erase.png)  *Erase display* +Erases the currently selected map display to a white background, see +*[d.erase](d.erase.md)*. + +![icon](icons/pointer.png)  *Pointer* +Select arrow cursor for map display. + +![icon](icons/select.png)  *Select features from vector map* +Interactively select features from given vector map. Selection can be +stored to a new vector map, see *[v.what](v.what.md)* and +*[v.extract](v.extract.md)*. + +![icon](icons/info.png)  *Query raster/vector maps* +Query selected raster, RGB raster (all three map channels will be +queried), or vector map(s) using the mouse. Map(s) must be selected +before query. Vector charts and thematic vector maps cannot be queried. +The results of the query will be displayed in a dialog. See +*[r.what](r.what.md), [v.what](v.what.md)*. + +![icon](icons/pan.png)  *Pan* +Interactive selection of a new center of view in the active display +monitor. Drag the pan cursor while pressing the left mouse button to +pan. Panning changes the location of the region displayed but not the +size of the area displayed or the resolution. Panning does *not* affect +the computational region for other GIS processes, see +*[g.region](g.region.md)*. + +![icon](icons/zoom-in.png)  *Zoom in* +Interactive zooming with the mouse in the active display monitor. +Drawing a box or just click with the mouse (left button) and zoom-in +cursor causes the display to zoom in so that the area defined by the box +fills the display. The map resolution is not changed. Clicking with the +zoom-in cursor causes the display to zoom in by 30%, centered on the +point where the mouse is clicked. Zooming resets the display region +extents (both size and location of area displayed). It does *not* affect +the computational region for other GIS processes, see +*[g.region](g.region.md)*. + +![icon](icons/zoom-out.png)  *Zoom out* +Interactive zooming with the mouse in the active display monitor. +Drawing a box or just click with the mouse (left button) and zoom-out +cursor causes the display to zoom in so that the area displayed shrinks +to fill the area defined by the box. The map resolution is not changed. +Clicking with the zoom-out cursor causes the display to zoom out by 30%, +centered on the point where the mouse is clicked. Zooming resets the +display region extents (both size and location of area displayed). It +does *not* affect the computational region for other GIS processes, see +*[g.region](g.region.md)*. + +![icon](icons/zoom-extent.png)  *Zoom to selected map(s)* +Set zoom extent based on selected raster or vector maps. Zooming resets +the display region extents (both size and location of area displayed). +It does *not* affect the computational region for other GIS processes, +see *[g.region](g.region.md)*. + +![icon](icons/zoom-region.png)  *Zoom to computational region extent* +Set zoom extent based on the current computational region extent, see +*[g.region](g.region.md)*. + +![icon](icons/zoom-last.png)  *Return to previous zoom* +Returns to the previous zoom extent. Up to 10 levels of zoom back are +maintained, see *[g.region](g.region.md)*. + +![icon](icons/zoom-more.png)  *Various zoom options* +Opens a dropdown menu that allows user to: + +- *Zoom to default region* +- *Zoom to saved region*. Zooms to previously saved named region. +- *Set computational region extent from display.* The computational + region (the mapset's `WIND` file) is set to match the current display + extent (does not change the resolution), see + *[g.region](g.region.md)*. +- *Set computational region extent interactively.* The computational + region is set simply by drawing a box with the left mouse button on + Map Display. +- *Set computational region from named region*. This option doesn't + affect display zoom. +- *Save display geometry to named region* +- *Save computational region to named region* + +![icon](icons/layer-raster-analyze.png)  *Analyze menu* +Opens a dropdown menu with: + +![icon](icons/measure-length.png)  *Measure distance* +Interactive measurement of lengths defined with the mouse. The length of +each segment and the cumulative length of all segments measuered is +displayed in the command output window frame. Lengths are measured in +the current measurement unit. Double-click to switch off measuring. + +![icon](icons/area-measure.png)  *Measure area* +Interactive measurement of area defined with the mouse. Area is measured +in the current measurement unit. Double-click to switch off measuring. + +![icon](icons/layer-raster-profile.png)  *Profile surface map* +Interactively create profile of a raster map. Profile transect is drawn +with the mouse in map display. The profile may be of the displayed map +or a different map. Up to three maps can be profiled simultaneously. + +![icon](icons/layer-raster-profile.png)  *Create bivariate scatterplot of raster maps* +Interactively create bivariate scatterplot of raster maps. + +![icon](icons/layer-raster-histogram.png)  *Create histogram of raster map* +Displays histogram of selected raster map or image in new window. + +![icon](icons/layer-raster-histogram.png)  *Create histogram with d.histogram* +Displays histogram of selected raster map or image in new window, see +*[d.histogram](d.histogram.md)*. + +![icon](icons/vector-tools.png)  *Vector network analysis tool* +See tool's [manual page](wxGUI.vnet.md). + +![icon](icons/overlay-add.png)  *Add overlay* +opens a dropdown menu that allows user to + +![icon](icons/legend-add.png)  *Add raster map legend* +Adds layer to display with legend of selected raster map, see +*[d.legend](d.legend.md)*. + +![icon](icons/scalebar-add.png)  *Add scalebar* +Adds layer to display a scalebar. Options include scalebar placement +(using screen coordinates or a mouse), scalebar format, and scalebar +colors, see *[d.barscale](d.barscale.md)*. + +![icon](icons/north-arrow-add.png)  *Add north arrow* +Adds layer to display a north arrow. Options include north arrow +placement (using screen coordinates or a mouse), north arrow style and +color, see *[d.northarrow](d.northarrow.md)*. + +![icon](icons/text-add.png)  *Add text layer* +Adds layer to display a line of text using default GRASS font (selected +with *[d.font](d.font.md)*). Options include: text placement (screen +coordinates); and text size, bolding, and color, see +*[d.text](d.text.md)*. + +![icon](icons/map-export.png)  *Save display to graphic file* +Save the visible image in map display to different raster graphic +formats. + +![icon](icons/print.png)  *Print map* +Prints map on system native printer or PostScript device; saves visible +map display (including PostScript text and labels) to PDF or EPS file. + +*Map display mode* +Opens a dropdown menu for selecting different display mode + +*2D view* +Normal GIS display. All active layers are composited and displayed in 2D +mode. + +*3D view* +Experimental replacement for NVIZ. Displays all active layers in 3D +perspective using OpenGL. A new control panel opens to manage the 3D +view. 3D view can be zoomed, panned, rotated, and tilted. The vertical +exaggeration of rasters and 3D vectors can be set. Various color and +lighten settings are possible. Not yet functional for Windows platforms + +*Vector digitizer* +Puts display into vector digitizing mode and opens a new digitizing +toolbar. The user can digitize a new vector map or edit an existing map. + +*Raster digitizer* +Puts display into raster digitizing mode and opens a new digitizing +toolbar. The user can digitize a new raster map or edit an existing map. + +### Keyboard short-cuts + +#### Layer Manager + +Ctrl+Tab +Switch 'Layers' and 'Console' tab + +Ctrl+Q +Quit + +Ctrl+R +Render map in all map displays + +**Workspace** + +Ctrl+N +Create new workspace + +Ctrl+O +Load workspace from file + +Ctrl+S +Close workspace + +**Layers** + +Ctrl+Shift+L +Add multiple raster or vector map layers to current map display + +Ctrl+Shift+R +Add raster map layer to current map display + +Ctrl+Shift+V +Add vector map layer to current map display + +Ctrl+W +Close current map display + +**Console** + +Tab +Show command tooltips + +Esc +Hide command tooltips + +Ctrl+Space +Show auto-complete suggestions + +Up/Down +List command history + +Enter +Run command + +Ctrl++ +Increase font size (numerical keyboard plus key) + +Ctrl+- +Decrease font size (numerical keyboard minus key) + +Ctrl+mouse wheel +Increase or decrease font size + +#### Map Display + +F11 +Fullscreen mode (toggle on/off) + +Ctrl+W +Close map display + +Ctrl+R +Render map (re-renders map) + +F5 +Render map (re-renders map) + +F6 +Enable/disable auto-rendering map (re-renders map) + +### Starting the GUI from command line + +By default, the GUI is always started, but if only the command line +(shell) is running, the GUI can be also started manually using: + +```bash +g.gui +``` + +If the wxGUI is not the default user interface, it can defined as +default by typing at the GRASS GIS command line: + +```bash +g.gui -d wxpython +``` + +Alternatively, it may be defined in the main configuration file +(`$HOME/.grass8/rc` on GNU/Linux and macOS, +`%APPDATA%\Roaming\GRASS8\rc` on MS Windows) using the `GUI` variable +set to `wxpython` (`GUI: wxpython`) or by the environmental variable +`GRASS_GUI`. To start with a previously saved workspace file: + +```bash +g.gui workspace=file.gxw +``` + +The user can also start GRASS from the shell command line with the wxGUI +specifying the `--gui` switch: + +```bash +grass --gui +``` + +The GUI can be quit by selecting the 'File \> Quit GRASS GIS' menu item +which gives options to close only GUI or to quit GRASS GIS entirely if +GRASS GIS is running with a command line (a shell in a terminal +application). Exiting the shell (typically by the `exit` command) ends +the GRASS session including any running GUIs. + +### Background information + +**wxGUI** is a native *Graphical User Interface* (GUI) for GRASS GIS +written in [Python](https://www.python.org) using +[wxPython](https://www.wxpython.org) library. + +## SEE ALSO + +*[wxGUI components](wxGUI.components.md), [wxGUI module +dialogs](wxGUI.modules.md), [wxGUI toolboxes (menu +customization)](wxGUI.toolboxes.md)* + +See also wxGUI [wiki](https://grasswiki.osgeo.org/wiki/WxGUI) page +(especially various [video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI#Video_tutorials)), and +[Quick wxGUI +Tutorial](https://grasswiki.osgeo.org/wiki/Quick_wxGUI_tutorial). + +## AUTHORS + +Martin Landa, FBK-irst (2007-2008), Trento, Italy, and Czech Technical +University in Prague, Czech Republic +Michael Barton, Arizona State University, USA +Daniel Calvelo Aros +Jachym Cepicky +Markus Metz, Germany +Anna Kratochvilova, OSGeoREL, Czech Technical University in Prague, +Czech Republic +Vaclav Petras, OSGeoREL, Czech Technical University in Prague, Czech +Republic +Stepan Turek, OSGeoREL, Czech Technical University in Prague, Czech +Republic +Tereza Fiedlerova, OSGeoREL, Czech Technical University in Prague, Czech +Republic +Matej Krejci, OSGeoREL, Czech Technical University in Prague, Czech +Republic + +Icons created by [Robert Szczepanek](http://robert.szczepanek.pl), +Poland ([Git repository](https://github.com/Cracert/GIS-icons)) diff --git a/gui/wxpython/docs/wxGUI.modules.md b/gui/wxpython/docs/wxGUI.modules.md new file mode 100644 index 00000000000..a7d136a129a --- /dev/null +++ b/gui/wxpython/docs/wxGUI.modules.md @@ -0,0 +1,179 @@ +## KEYWORDS + +[general](general.md), [GUI](topic_GUI.md) + +## DESCRIPTION + +GRASS GIS functionality is organized into modules, which are standalone +programs with defined interface. Their graphical user interface (GUI) is +a dialog with several tabs which organize module parameters into groups. + +Each parameter can have different type of input fields, for example text +entry or drop-down list. Flags are represented as checkboxes. The +parameter (or flag) name is visible on the right side of each input +field so that it is simple to understand how the module dialog relates +to the command representation which is used in the manuals and +tutorials. The commands can be used to call the module in the command +line, Shell scripts or, with a slight modification, in a Python script. + + + +### Tabs + +Module parameters and flags are organized in tabs. Their names can +depend on a module, however every module has *Command output* tab where +the progress can be observed, and the module output including text +results or warnings are printed. The last *Manual* tab contains +description of module's parameters and examples. The same information +can be found in the online manual as well. + +The style of the tabs can be changed through *GUI settings* - +*Appearance* - *Module dialog style*. Note that the style appearance +depends on the platform and some styles might be more suitable for +different platforms. + + + +Figure: Example of style "left" and "top" on Ubuntu. + +### Flags + +Module flags are represented as checkboxes with description. There are +three special flags - *overwrite*, *verbose* and *quiet*. Flags +*verbose* and *quiet* set the level of verbosity of the module (how +detailed the messages should be). + +dialog flags + +Modules which output a new map or a new file have the flag *overwrite* +which must be used when the specified output map or file is already +present. If the map or file of the specified name already exist and +*overwrite* flag is not used, an error message appears: + +```bash +r.slope.aspect elevation=elevation slope=slope +ERROR: option : exists. To overwrite, use the --overwrite flag +``` + +If using the command instead of GUI, these flags are unlike other flags +prefixed with double dash: + +```bash +r.slope.aspect elevation=elevation slope=slope --overwrite --quiet +``` + +### Current working directory + +Certain modules require a file as input or output. Either the full path +to the file needs to be specified or a path relative to the current +working directory is enough, for example only the name of the file. +**Current working directory** is a directory where GRASS would look for +or output files to if the full path is not specified. By default working +directory is user's home folder. It can be changed in wxGUI menu +*Settings* - *GRASS working environment* - *Change working directory*, +or by typing `cd` and pressing Enter in the wxGUI Command console. If +the working directory is changed to a directory where the input files +are, then it is enough to specify just the name of the file instead of +the full path. + +This applies to external files such as text files or GeoTiff files. This +does not apply to raster maps, vector maps and other geospatial data +stored in GRASS database which do not need any path to be specified. + +### Special widgets + +For raster, vector or 3D raster input, there is a special widget which +after clicking on the arrow to the right pops up a list of existing maps +from different mapsets. Selecting a map from the popup list will add it +to the entry field. In case multiple maps can be specified (denoted by +*\[multiple\]* label), selecting a map from the popup list will append +the map names with comma in between. + + + +If the input file is supposed to be a text file (for example color rules +in r.colors), it is possible to type the text in the provided box +directly instead of creating a new file in a text editor and saving it. +A temporary file is created in this case. By pressing the *Save as* +button, the content of the box is then saved into user specified file, +so that user's workflow can be reproduced later. With *Load* button we +can display the content of selected file and edit it directly in the +box. + + + + +Figure: In the first image, user specified a full path to a file. In the +second image, user typed color rules conveniently into the box below, +however the rules will not be stored permanently. + +## NOTES + +Dialogs are generated automatically based on module interface defined +using [g.parser](g.parser.md). Command line interface can be obtained +when running the module with a *--help* flag. The options and flags are +the same as in the module GUI. + +```bash +r.neighbors --help + +Description: + Makes each cell category value a function of the category +values assigned to the cells around it, and stores new cell +values in an output raster map layer. +Keywords: + raster, algebra, statistics, aggregation, neighbor, focal +statistics, filter +Usage: + r.neighbors [-ac] input=name [selection=name] +output=name[,name,...] + [method=string[,string,...]] [size=value] [title=phrase] +[weight=name] + [gauss=value] [quantile=value[,value,...]] [--overwrite] +[--help] + [--verbose] [--quiet] [--ui] +Flags: + -a Do not align output with the input + -c Use circular neighborhood + --o Allow output files to overwrite existing files + --h Print usage summary + --v Verbose module output + --q Quiet module output + --ui Force launching GUI dialog +Parameters: + input Name of input raster map + selection Name of an input raster map to select the +cells which should be processed + output Name for output raster map + method Neighborhood operation + options: +average,median,mode,minimum,maximum,range,stddev,sum, +count,variance,diversity,interspersion,quart1,quart3, + perc90,quantile + default: average + size Neighborhood size + default: 3 + title Title for output raster map + weight Text file containing weights + gauss Sigma (in cells) for Gaussian filter + quantile Quantile to calculate for method=quantile + options: 0.0-1.0 +``` + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +## AUTHORS + +GRASS Development Team +manual by Anna Petrasova, OSGeoREL, Faculty of Civil Engineering, Czech +Technical University in Prague +Vaclav Petras, OSGeoREL, Faculty of Civil Engineering, Czech Technical +University in Prague diff --git a/gui/wxpython/docs/wxGUI.nviz.md b/gui/wxpython/docs/wxGUI.nviz.md new file mode 100644 index 00000000000..62d60fa4c85 --- /dev/null +++ b/gui/wxpython/docs/wxGUI.nviz.md @@ -0,0 +1,377 @@ +## KEYWORDS + +[display](display.md), [GUI](topic_GUI.md), +[visualization](keywords.md#visualization), +[graphics](keywords.md#graphics), [raster](keywords.md#raster), +[vector](keywords.md#vector), [raster3d](keywords.md#raster3d) + +## DESCRIPTION + +Note: **wxNviz is currently under development. Not all planned +functionality is already implemented.** + +**wxNviz** is a *[wxGUI](wxGUI.md)* **3D view mode** which allows users +to realistically render multiple *surfaces* (2D raster maps) in a 3D +space, optionally using thematic coloring, draping 2D *vector* data or +different 2D raster data over the surfaces, displaying 3D vector data in +the space, and visualization of *3D rasters*. + +To start the wxGUI 3D view mode, choose '3D view' from the map toolbar. +You can switch between 2D and 3D view. The region in 3D view is updated +according to displayed region in 2D view. + +wxNviz is emphasized on the ease and speed of viewer positioning and +provided flexibility for using a wide range of data. A low resolution +surface or wire grid (optional) provides real-time viewer positioning +capabilities. Coarse and fine resolution controls allow the user to +further refine drawing speed and detail as needed. Continuous scaling of +elevation provides the ability to use various data types for the +vertical dimension. + +For each session of wxNviz, you might want the same set of 2D/3D raster +and vector data, view parameters, or other attributes. For consistency +between sessions, you can store this information in the GRASS +*workspace* file (gxw). Workspace contains information to restore +"state" of the system in 2D and if wxNviz is enabled also in the 3D +display mode. + +## 3D View Toolbar + +toolbar + +![icon](icons/script-save.png)  *Generate command for m.nviz.image* +Generate command for m.nviz.image based on current state. + +![icon](icons/settings.png)  *Show 3D view mode settings* +Show dialog with settings for wxGUI 3D view mode. The user settings can +be stored in wxGUI settings file. + +![icon](icons/help.png)  *Show help* +Show this help. + +## 3D View Layer Manager Toolbox + +The 3D view toolbox is integrated in the Layer Manager. The toolbox has +several tabs: + +- **View** for view controlling, +- **Data** for data properties, +- **Appearance** for appearance settings (lighting, fringes, ...). +- **Analysis** for various data analyses (only cutting planes so far). +- **Animation** for creating simple animations. + +### View + +You can use this panel to set the *position, direction, and perspective* +of the view. The position box shows a puck with a direction line +pointing to the center. The direction line indicates the look direction +(azimuth). You click and drag the puck to change the current eye +position. Another way to change eye position is to press the buttons +around the position box representing cardinal and ordinal directions. + +There are four other buttons for view control in the bottom of this +panel (following label *Look:*): + +- *here* requires you to click on Map Display Window to determine the + point to look at. +- *center* changes the point you are looking at to the center. +- *top* moves the current eye position above the map center. +- *reset* returns all current view settings to their default values. + +toolbox + +You can adjust the viewer's height above the scene, perspective and +twist value to rotate the scene about the horizontal axis. An angle of 0 +is flat. The scene rotates between -90 and 90 degrees. + +You can also adjusts the vertical exaggeration of the surface. As an +example, if the easting and northing are in meters and the elevation in +feet, a vertical exaggeration of 0.305 would produce a true +(unexaggerated) surface. + +View parameters can be controlled by sliders or edited directly in the +text boxes. It is possible to enter values which are out of slider's +range (and it will then adjust to the new range). + +#### Fly-through mode + +View can be changed in fly-through mode (can be activated in Map Display +toolbar), which enables to change the view smoothly and therefore it is +suitable for creating animation (see below). To start flying, press left +mouse button and hold it down to continue flying. Flight direction is +controlled by mouse cursor position on screen. Flight speed can be +increased/decreased stepwise by keys PageUp/PageDown, Home/End or +Up/Down arrows. Speed is increased multiple times while Shift key is +held down. Holding down Ctrl key switches flight mode in the way that +position of viewpoint is changed (not the direction). + +### Data properties + +This tab controls the parameters related to map layers. It consists of +four collapsible panels - *Surface*, *Constant surface*, *Vector* and +*3D raster*. + +#### Surface + +Each active raster map layer from the current layer tree is displayed as +surface in the 3D space. This panel controls how loaded surfaces are +drawn. To change parameters of a surface, it must be selected in the +very top part of the panel. + +The top half of the panel has drawing style options. Surface can be +drawn as a wire mesh or using filled polygons (most realistic). You can +set draw **mode** to *coarse* (fast display mode), *fine* (draws surface +as filled polygons with fine resolution) or *both* (which combines +coarse and fine mode). Additionally set coarse **style** to *wire* to +draw the surface as wire mesh (you can also choose color of the wire) or +*surface* to draw the surface using coarse resolution filled polygons. +This is a low resolution version of the polygon surface style. E.g. +surface is drawn as a wire mesh if you set **mode** to *coarse* and +**style** to *wire*. Note that it differs from the mesh drawn in fast +display mode because hidden lines are not drawn. To draw the surface +using filled polygons, but with wire mesh draped over it, choose +**mode** *both* and **style** *wire*. Beside mode and style you can also +choose style of **shading** used for the surface. *Gouraud* style draws +the surfaces with a smooth shading to blend individual cell colors +together, *flat* draws the surfaces with flat shading with one color for +every two cells. The surface appears faceted. + +To set given draw settings for all loaded surfaces press button "Set to +all". + +The bottom half of the panel has options to set, unset or modify +attributes of the current surface. Separate raster data or constants can +be used for various attributes of the surface: + +- **color** - raster map or constant color to drape over the current + surface. This option is useful for draping imagery such as aerial + photography over a DEM. +- **mask** - raster map that controls the areas displayed from the + current surface. +- **transparency** - raster map or constant value that controls the + transparency of the current surface. The default is completely opaque. + Range from 0 (opaque) to 100 (transparent). +- **shininess** - raster map or constant value that controls the + shininess (reflectivity) of the current surface. Range from 0 to 100. + +In the very bottom part of the panel position of surface can be set. To +move the surface right (looking from the south) choose *X* axis and set +some positive value. To reset the surface position press *Reset* button. + +toolbox + +#### Constant surface + +It is possible to add constant surface and set its properties like fine +resolution, value (height), color and transparency. It behaves similarly +to surface but it has less options. + +#### Vector + +2D vector data can be draped on the selected surfaces with various +markers to represent point data; you can use attribute of vector +features to determine size, color, shape of glyph. 3D vector data +including volumes (closed group of faces with one kernel inside) is also +supported. This panel controls how loaded 2D or 3D vector data are +drawn. + +You can define the width (in pixels) of the line features, the color +used for lines or point markers. + +If vector map is 2D you can display vector features as flat at a +specified elevation or drape it over a surface(s) at a specified height. +Use the height control to set the flat elevation or the drape height +above the surface(s). In case of multiple surfaces it is possible to +specify which surfaces is the vector map draped over. + +For display purposes, it is better to set the height slightly above the +surface. If the height is set at zero, portions of the vector may +disappear into the surface(s). + +For 2D/3D vector points you can also set the size of the markers. +Currently are implemented these markers: + +- **x** sets the current points markers to a 2D "X", +- **sphere** - solid 3D sphere, +- **diamond** - solid 3D diamond, +- **cube** - solid 3D cube, +- **box** - hollow 3D cube, +- **gyroscope** - hollow 3D sphere, +- **asterisk** - 3D line-star. + +Thematic mapping can be used to determine marker color and size (and +line color and width). + +toolbox + +#### 3D rasters + +3D raster maps (volumes, voxel models) can be displayed either as +isosurfaces or slices. Similarly to surface panel you can define draw +**shading** - *gouraud* (draws the 3D rasters with a smooth shading to +blend individual cell colors together) and *flat* (draws the 3D rasters +with flat shading with one color for every two cells. The 3D raster +appears faceted). As mentioned above currently are supported two +visualization modes: + +- **isosurface** - the levels of values for drawing the 3D raster(s) as + isosurfaces, +- and **slice** - drawing the 3D raster as cross-sections. + +The middle part of the panel has controls to add, delete, move up/down +selected isosurface or slice. The bottom part differs for isosurface and +slice. When choosing an isosurface, this part the of panel has options +to set, unset or modify attributes of the current isosurface. Various +attributes of the isosurface can be defined, similarly to surface +attributes: + +- **isosurface value** - reference isosurface value (height in map + units). +- **color** - raster map or constant color to drape over the current 3D + raster. +- **mask** - raster map that controls the areas displayed from the + current 3D raster. +- **transparency** - raster map or constant value that controls the + transparency of the current 3D raster. The default is completely + opaque. Range from 0 (opaque) to 100 (transparent). +- **shininess** - raster map or constant value that controls the + shininess (reflectivity) of the current 3D raster. Range from 0 to + 100. + +In case of 3D raster slice the bottom part of the panel controls the +slice attributes (which axis is slice parallel to, position of slice +edges, transparency). Press button *Reset* to reset slice position +attributes. + +3D rasters can be moved the same way like surfaces do. + +toolbox + +### Analysis + +*Analysis* tab contains *Cutting planes* panel. + +#### Cutting planes + +Cutting planes allow cutting surfaces along a plane. You can switch +between six planes; to disable cutting planes switch to *None*. +Initially the plane is vertical, you can change it to horizontal by +setting *tilt* 90 degrees. The *X* and *Y* values specify the rotation +center of plane. You can see better what *X* and *Y* do when changing +*rotation*. The *Height* parameter applies only when changing *tilt* +concurrently. Press the *Reset* button to reset the current cutting +plane. + +In case of multiple surfaces you can visualize the cutting plane by +*Shading*. Shading is visible only when more than one surface is loaded +and these surfaces must have the same fine resolution set. + +### Appearance + +Appearance tab consists of three collapsible panels: + +- *Lighting* for adjusting light source +- *Fringe* for drawing fringes +- *Decorations* to display north arrow and scale bar + +The *lighting* panel enables to change the position of light source, +light color, brightness and ambient. Light position is controlled +similarly to eye position. If option *Show light model* is enabled light +model is displayed to visualize the light settings. + +toolbox + +The *Fringe* panel allows you to draw fringes in different directions +(North & East, South & East, South & West, North & West). It is possible +to set the fringe color and height of the bottom edge. + +The *Decorations* panel enables to display north arrow and simple scale +bar. North arrow and scale bar length is determined in map units. You +can display more than one scale bar. + +### Animation + +Animation panel enables to create a simple animation as a sequence of +images. Press 'Record' button and start changing the view. Views are +recorded in given interval (FPS - Frames Per Second). After recording, +the animation can be replayed. To save the animation, fill in the +directory and file prefix, choose image format (PPM or TIF) and then +press 'Save'. Now wait until the last image is generated. It is +recommended to record animations using fly-through mode to achieve +smooth motion. + +## Settings + +This panel has controls which allows user to set default surface, vector +and 3D raster data attributes. You can also modify default view +parameters, or to set the background color of the Map Display Window +(the default color is white). + +## To be implemented + +- Labels, decoration, etc. (Implemented, but not fully functional) +- Surface - mask by zero/elevation, more interactive positioning +- Vector points - implement display mode flat/surface for 2D points +- ... + +## NOTE + +wxNviz is under active development and distributed as "Experimental +Prototype". + +Please note that with wxGTK port of wxPython (Linux systems), a problem +might appear during wxNviz initialization (nothing is rendered at all) +or when rendering vectors (bad order of rendering surfaces and vectors). +If you encounter such problems, try to change a depth buffer number in +*wxGUI Settings \> Preferences \> Map Display \> Advanced* (possible +numbers are 0, 16, 24, 32). It is currently not possible to +automatically determine the right number which is working for your +computer. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +See also [wiki](https://grasswiki.osgeo.org/wiki/WxNVIZ) page +(especially various [video +tutorials](https://grasswiki.osgeo.org/wiki/WxNVIZ#Video_tutorials)). + +Command-line module *[m.nviz.image](m.nviz.image.md)*. + +## AUTHORS + +**The wxNviz GUI** + +[Martin Landa](http://geo.fsv.cvut.cz/gwiki/Landa), [Google Summer of +Code 2008](https://grasswiki.osgeo.org/wiki/WxNviz_GSoC_2008) (mentor: +Michael Barton) and +[2010](https://grasswiki.osgeo.org/wiki/WxNviz_GSoC_2010) (mentor: +Helena Mitasova) +Anna Kratochvilova, [Google Summer of Code +2011](https://grasswiki.osgeo.org/wiki/WxNviz_GSoC_2011) (mentor: Martin +Landa) + +**The OGSF library and NVIZ engine** + +NVIZ (GRASS's *n*-dimensional visualization suite) was written by Bill +Brown, Terry Baker, Mark Astley, and David Gerdes, U.S. Army Corps of +Engineers Research Laboratories, Champaign, Illinois and UI GMS +Laboratory, Urbana, IL in the early 1990s. + +Original documentation was written by Terry Baker (spring 1995), and +updated by Mark Astley, based on a document written by Bill Brown. +Additional design help and funding in the early 1990s by Helena Mitasova +(CERL). Tcl/Tk support added by Terry Baker. Ported to Linux by Jaro +Hofierka and others. Conversion from SGI IRIS GL code to OpenGL by +Justin Hickey. Further program and documentation (2004) updates by Bob +Covill, Tekmap Consulting. 3D volume support by Tomas Paudits with +supervision from Jaro Hofierka and Helena Mitasova. Fly-through mode, +thematic site attributes, and picking by Massimo Cuomo (ACS) with +updates by Michael Barton. GRASS 6 vector support by Radim Blazek. +Additional updates by Markus Neteler, Martin Landa, Glynn Clements, and +Hamish Bowman. + +NVIZ evolved from the earlier GRASS program *SG3d* written for Silicon +Graphics IRIS GL by Bill Brown and Dave Gerdes at USA CERL, 1990-1995 +and from the NVIZ Motif version written by Bill Brown with contributions +by Terrance McGhee. diff --git a/gui/wxpython/docs/wxGUI.toolboxes.md b/gui/wxpython/docs/wxGUI.toolboxes.md new file mode 100644 index 00000000000..b60ec3305a0 --- /dev/null +++ b/gui/wxpython/docs/wxGUI.toolboxes.md @@ -0,0 +1,198 @@ +## KEYWORDS + +[general](general.md), [GUI](topic_GUI.md) + +## DESCRIPTION + +The **Toolboxes** is a way to customize items in *[wxGUI](wxGUI.md)* +menu. Toolboxes enable to: + +- hide unused menu items in menu (e.g. Imagery, Database) or submenu + (e.g. Wildfire modeling) +- change order of menu items and subitems +- add new menu items (e.g. Temporal) +- add addons modules +- add your own modules + +Toolboxes are configured through two XML files (`main_menu.xml` and +`toolboxes.xml`) located in your user home GRASS directory, subdirectory +`toolboxes` (`$HOME/.grass8/toolboxes/` on UNIX). Currently, there is no +GUI front-end for toolboxes, however only simple editing of text files +is needed. + +### Brief description of file `main_menu.xml` + +This file represents the main menu (File, Settings, Raster, ...). By +modifying this file you show and hide menu items which are represented +by `subtoolbox` tag. + +Tag `user-toolboxes-list` is interpreted as a menu containing a list of +all user-defined toolboxes. If not needed it can be removed. + +Following lines can be copied to `.grass8/toolboxes/main_menu.xml` and +by removing, adding or reordering lines users can change the main menu +items. See further examples. + +```bash + + + + + + + + + + + + + + + +``` + +### Brief description of file `toolboxes.xml` + +This file contains structure and description of individual toolboxes. +Note that both *Raster* and e.g. *Query raster maps* are individual +toolboxes although one contains the other. Tag `toolbox` contains +`subtoolbox` tags which are defined later in the file. These nested +toolboxes are linked through `name` attribute. + +Apart from `subtoolbox` tag, tag `toolbox` can contain individual items +(modules) and separators (for visual separation in the menu tree). + +```bash + + + + + + + + + + + + + + ... + ... + + + + + + + + + + + +``` + +To redefine a toolbox (or use it as a template), copy specific part of +file `grass7/gui/wxpython/xml/toolboxes.xml` from GRASS installation to +a new file in user home (`.grass8/toolboxes/toolboxes.xml`) and edit it. +Rename this new toolbox. + +## EXAMPLES + +### Hiding menu items + +If we are for example working only with raster data, we can hide menu +items *Vector* and *Database*. The file `main_menu.xml` then contains +the following lines where we omitted the two toolboxes: + +```bash + + + + + + + + + + + + + +``` + +### Creating custom toolbox + +In this example we create a new toolbox *Favorites* containing existing +GRASS module and toolbox, custom module created by the user and addon +module. The `toolboxes.xml` file contains following lines: + +```bash + + + + + + + + + + + + + + + + + + + + + + +``` + +Optionally, we can add this toolbox to the main menu items. The +`main_menu.xml` file contains following lines: + +```bash + + + + + + + + + + + + + + + + +``` + +If we have `user-toolboxes-list` tag in the `main_menu.xml` file, our +custom toolbox will be listed in the automatically added *Toolboxes* +main menu item. The screenshot shows the resulting menu: + + + +## NOTES + +After the first start of wxGUI with custom toolboxes, `.grass/toolboxes` +directory will contain file `menudata.xml` which is auto-generated and +should not be edited. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +## AUTHORS + +Anna Petrasova, OSGeoREL, Faculty of Civil Engineering, Czech Technical +University in Prague +Vaclav Petras, OSGeoREL, Faculty of Civil Engineering, Czech Technical +University in Prague diff --git a/gui/wxpython/docs/wxGUI.vnet.md b/gui/wxpython/docs/wxGUI.vnet.md new file mode 100644 index 00000000000..b3ccd2ebaa2 --- /dev/null +++ b/gui/wxpython/docs/wxGUI.vnet.md @@ -0,0 +1,89 @@ +## KEYWORDS + +[vector](vector.md), [network](topic_network.md), +[vector](keywords.md#vector) + +## DESCRIPTION + +**Vector Network Analysis Tool** is graphical front-end for `v.net*` +modules. It allows perform network analysis directly in +*[wxGUI](wxGUI.md)* without need to use command line. The tool can be +launched from Layer Manager menu *Vector → Network analysis → Vector +network analysis tool* or from Map Display toolbar *Analyse map → Vector +network analysis tool* ![icon](icons/vector-tools.png). + + +Subsets for nearest centers (*[v.net.alloc](v.net.alloc.md)*) + +*Vector Network Analysis Tool* currently allows you to: + +- perform these network analyses: + - Shortest path (*[v.net.path](v.net.path.md)*) + - Salesman (*[v.net.salesman](v.net.salesman.md)*) + - Flow (*[v.net.flow](v.net.flow.md)*) + - Allocate subnets for nearest centers + (*[v.net.alloc](v.net.alloc.md)*) + - Steiner tree for the network and given terminals + (*[v.net.distance](v.net.distance.md)*) + - Splits net by cost isolines (*[v.net.iso](v.net.iso.md)*) +- show and set all data needed for the analysis (points, attribute + tables, compute costs) +- show analysis results (maps and it's attribute tables) +- snapping to nodes +- browse previous analysis results + +## NOTES + +The tool is split into tabs. Every tab represents some functionality: + +**Parameters** tab +It is used for setting vector map and it's layer on which analysis will +be done. Also it is possible to set columns with cost values from +attribute table connected to particular layer. + +**Points** tab +It manages points, which are used for analysis. + +**Output** tab +There is a output console, which shows information about running +analysis. + +**Input tables** tab +When existing vector map and it's existing layers are set in +*Parameters* tab, this tab is dynamically added. It shows attribute +tables of node and arc layers, which were chosen for analysis. It is +also possible to compute cost values in this tab. This can be done by +right mouse button click on column label. Then from pop-up menu choose +*Add column*, where new column for cost values can be created. After +that by right mouse button click on the added column label can be chosen +item *Field calculator*. This tool computes cost values. + +**Result tables** tab +The result of vector network analysis is always a vector map. Some +vector network analysis results can also include attribute tables. If +such a table is connected to the result map, this tab is shown and with +it you can browse the data. + +## KNOWN ISSUES + +When some change is done in layer tree of Map Display, temporary vector +map representing result of analysis is not rendered (use *Show result* +button in toolbar to render it again). + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +See list of [vector network modules](topic_network.md). + +See also the user +[wiki](https://grasswiki.osgeo.org/wiki/WxGUI_Vector_Network_Analysis_Tool) +page including [video +tutorial](https://grasswiki.osgeo.org/wiki/WxGUI-Vector-Network-Analysis-Tool#Video-tutorial). + +## AUTHOR + +Stepan Turek, [Google Summer of Code +2012](https://grasswiki.osgeo.org/wiki/GRASS_GSoC_2012_WxGUI_front_end_for_vector_analysis_modules) +(mentor: Martin Landa) diff --git a/gui/wxpython/gcp/g.gui.gcp.md b/gui/wxpython/gcp/g.gui.gcp.md new file mode 100644 index 00000000000..71c21a6cf86 --- /dev/null +++ b/gui/wxpython/gcp/g.gui.gcp.md @@ -0,0 +1,261 @@ +## DESCRIPTION + +The **GCP Manager** is a *[wxGUI](wxGUI.md)* extension which allows the +user to create, edit, and manage Ground Control Points. It is available +from the menu "File \| Manage Ground Control Points". + +The **GCP Manager** provides an interactive graphical interface to +manage and analyze Ground Control Points. A backup copy of the initial +POINTS file is always maintained and updated only on request (Save GCPs +to POINTS file). This guarantees that accidental changes are not +permanent and can be undone by reloading the Ground Control Points. + +The GCP Manager must be started in the target project, not in the source +project. + +The GCP Manager is structured into three panels: + +- The topmost panel shows a list of Ground Control Points. Tools to + manipulate and analyze GCPs are provided in the toolbar. This panel + can be moved out of the GCP manager window by either dragging with the + caption or by clicking on the pin button on the right in the caption. + This panel can also be placed below the map displays by dragging. +- The two panels in the lower part are used for map and GCP display, the + left pane showing a map from the source project and the right pane + showing a reference map from the target project. Numbered Ground + Control Points are shown on both map displays. + +### Components of the GCP Manager + +GCP Manager + +*Toolbars* + +Two toolbars are provided with the GCP Manager, one for managing the map +displays and one for managing the GCP list. + +*List of ground control points* + +The list of Ground Control Points can be sorted by clicking on a column +header. Clicking on a column header will sort the GCPs ascending, a +second click on the same column will sort the GCPs descending. Overall +RMS error and individual RMS errors of all points are often improved if +the GCP with the highest RMS error is adjusted. Individual coordinates +can be edited by double-clicking on a row. + +The first column holds a checkbox and displays the point number. A GCP +is only used for RMS error calculation and georectification if its +checkbox on the left is checked. Uncheck to deactivate a GCP (mark as +unused GCP). + +*Two panels for map display* + +The left panel is used to display a map from the source project, the +right panel to display a map from the target project. Zooming in and out +is always possible with the mouse wheel and done for each map canvas +separately. + +GCPs are displayed in different colors, depending on whether a GCP has a +high RMS error, is currently unused or is currently selected. +Optionally, currently unused GCPs are not shown on the map display. + +*Statusbar* + +At the bottom of the GCP Manager is a statusbar providing several +functions. The default is set to *Go to GCP No.* (see also below). +Typing a number or using the up/down arrows will center the maps on the +given GCP, useful with a high zoom. + +#### GCP Map Display Toolbar + +![icon](icons/show.png)  *Display map* +Displays maps for source and target canvas and re-renders any layers +that have changed since the last time the display was updated. + +![icon](icons/layer-redraw.png)  *Re-render map* +Re-renders both source and target canvas regardless of whether they have +changed or not. + +![icon](icons/erase.png)  *Erase display* +Erases both source and target canvas to a white background. + +![icon](icons/gcp-create.png)  *Define GCP (Ground Control Points)* +On left mouse click, coordinates are defined for the currently selected +GCP. + +![icon](icons/pan.png)  *Pan* +Interactive selection of a new center of view in the active display +monitor. Drag the pan cursor while pressing the left mouse button to +pan. Alternatively left-click on the new center. Panning changes the +location of the region displayed but not the size of the area displayed +or the resolution. + +![icon](icons/zoom-in.png)  *Zoom in* +Interactive zooming with the mouse in the active map canvas (source or +target). Drawing a box or just a left click with the mouse and zoom-in +cursor causes the display to zoom in so that the area defined by the box +fills the display. The map resolution is not changed. Clicking with the +zoom-in cursor causes the display to zoom in by 30%, centered on the +point where the mouse is clicked. Zooming changes the display region +extents (both size and location of area displayed). + +![icon](icons/zoom-out.png)  *Zoom out* +Interactive zooming with the mouse in the active map canvas (source or +target). Drawing a box or just a left click with the mouse and zoom-out +cursor causes the display to zoom out so that the area displayed shrinks +to fill the area defined by the box. The map resolution is not changed. +Clicking with the zoom-out cursor causes the display to zoom out by 30%, +centered on the point where the mouse is clicked. Zooming changes the +display region extents (both size and location of area displayed). + +![icon](icons/zoom-more.png)  *Adjust display zoom* +Source and target display are adjusted by using the current GCPs for +coordinate transformation: + +*Adjust source display to target display* +The extents of the source display are adjusted to the current extents of +the target display. + +*Adjust target display to source display* +The extents of the source display are adjusted to the current extents of +the target display. + +*Set active map canvas* +Sets the currently active map canvas (source or target). Click to set +active map canvas for *Return to previous zoom* or *Zoom to extent of +currently displayed map*. Alternatively, move the mouse over the map +canvas to be used as active canvas. + +![icon](icons/zoom-last.png)  *Return to previous zoom* +Returns to the previous zoom extent. Up to 10 levels of zoom back are +maintained. + +![icon](icons/zoom-extent.png)  *Zoom to extent of currently displayed map* +Zoom to the extent of the currently displayed map in the active map +canvas (source or target). + +![icon](icons/settings.png)  *Settings* +Shows a settings dialog for GCP management and display: + +*Symbology* +Settings for map and GCP display: + +*Highlight highest RMS error only* +Only the GCP with the highest RMS error will be displayed in a different +colour, both in the list of GCPs and the GCP Map Display. + +*Factor for RMS error threshold = M + SD \* factor:* +All GCPs with an RMS error larger than mean RMS + RMS standard deviation +\* this factor will be displayed in a different colour, both in the list +of GCPs and the GCP Map Display. As a rule of thumb, GCPs with an RMS +error larger than *M + SD \* 2* are most probably wrong. GCPs with an +RMS error larger than *M + SD \* 1* are worth closer inspection. This +option is only available if *Highlight highest RMS error only* is +unchecked. + +*Color* +Set the color for GCPs on the GCP Map Display. + +*Color for high RMS error* +Set the color for GCPs with a high RMS error on the GCP Map Display. + +*Color for selected GCP* +Set the color for the currently selected GCP on the GCP Map Display. + +*Show unused GCPs* +If unchecked, unused GCPs will not be shown on the GCP Map Display. + +*Color for unused GCPs* +Set the color for unused GCPs on the GCP Map Display. + +*Symbol size* +Set the symbol size for GCPs on the GCP Map Display. + +*Line width* +Set the line width for GCPs on the GCP Map Display. + +*Select source map to display* +Select a source map for the left pane of the GCP Map Display. + +*Select target map to display* +Select a target map for the right pane of the GCP Map Display. + +*Rectification* +Settings for georectification: + +*Select rectification method* +Set the polynomial order for georectification. This order will also be +used for RMS error calculation. + +*Clip to computational region in target project* +Clip raster maps to the current computational region in the target +project when georectifying. + +*Extension for output maps* +Change the extension for output map names when doing the actual +georectification. + +![icon](icons/help.png)  *Show Help* +Show help page for the GCP Manager. + +![icon](icons/quit.png)  *Quit* +Quit the GCP Manager. + +#### Toolbar for the GCP list + +![icon](icons/gcp-save.png)  *Save GCPs to POINTS file* +The current list of GCPs is saved to the imagery group's POINTS file and +to a backup copy. + +![icon](icons/gcp-add.png)  *Add new GCP* +Adds a new Ground Control Point to the list and selects it for editing. + +![icon](icons/gcp-delete.png)  *Delete selected GCP* +Deletes the currently selected GCP from the list. + +![icon](icons/gcp-remove.png)  *Clear selected GCP* +Resets all coordinates of the currently selected GCP to 0 (zero). + +![icon](icons/reload.png)  *Reload GCPs from POINTS file* +Reloads GCPs from the imagery group's POINTS file. + +![icon](icons/gcp-rms.png)  *Recalculate RMS error* +Recalculates forward and backward RMS error for all GCP marked for use +(activated checkbox in first row). + +![icon](icons/georectify.png)  *Georectify* +Uses *[i.rectify](i.rectify.md)* to georectify all images in the source +imagery group. + +#### GCP Map Display Statusbar + +The GCP map display statusbar is similar to the statusbar in the regular +GRASS GIS map display with two differences, *Go to* has been replaced +with *Go to GCP No.* and *Projection* has been replaced with *RMS +error*. + +If *Go to GCP No.* is selected, a GCP number can be given in the left +side of the statusbar and the source and target map canvas will be +centered on the given GCP. Clicking on the map canvas will update +coordinates for this GCP. + +If *RMS error* is selected, the overall forward and backward RMS error +is displayed. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +*[i.rectify](i.rectify.md), [m.transform](m.transform.md), +[v.rectify](v.rectify.md)* + +See also [video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI/Video_tutorials#Georectifier) +on GRASS Wiki. + +## AUTHORS + +Markus Metz + +*Based on the Georectifier (GRASS 6.4.0)* by Michael Barton +Martin Landa, Czech Technical University in Prague, Czech Republic diff --git a/gui/wxpython/gmodeler/g.gui.gmodeler.md b/gui/wxpython/gmodeler/g.gui.gmodeler.md new file mode 100644 index 00000000000..b4e66f6c8d0 --- /dev/null +++ b/gui/wxpython/gmodeler/g.gui.gmodeler.md @@ -0,0 +1,388 @@ +## DESCRIPTION + +The **Graphical Modeler** is a *[wxGUI](wxGUI.md)* component which +allows the user to create, edit, and manage simple and complex models +using an easy-to-use interface. When performing analytical operations in +GRASS GIS, the operations are not isolated, but part of a chain of +operations. Using the Graphical Modeler, a chain of processes (i.e. +GRASS GIS modules) can be wrapped into one process (i.e. model). +Subsequently it is easier to execute the model later on even with +slightly different inputs or parameters. +Models represent a programming technique used in GRASS GIS to +concatenate single steps together to accomplish a task. It is +advantageous when the user see boxes and ovals that are connected by +lines and represent some tasks rather than seeing lines of coded text. +The Graphical Modeler can be used as a custom tool that automates a +process. Created models can simplify or shorten a task which can be run +many times and it can also be easily shared with others. Important to +note is that models cannot perform specified tasks that one cannot also +manually perform with GRASS GIS. It is recommended to first to develop +the process manually, note down the steps (e.g. by using the *Copy* +button in module dialogs) and later replicate them in model. + +The Graphical Modeler allows you to: + +- define data items (raster, vector, 3D raster maps) +- define actions (GRASS commands) +- define relations between data and action items +- define loops (e.g. map series) and conditions (if-else statements) +- define model variables +- parameterize GRASS commands +- define intermediate data +- validate and run model +- save model properties to a file (*GRASS Model File\|\*.gxm*) +- export model to Python script +- export model to Python script in the form of a PyWPS process +- export model to an actinia process +- export model to image file + +### Main dialog + +The Graphical Modeler can be launched from the Layer Manager menu +`File -> Graphical modeler` or from the main toolbar +![icon](icons/modeler-main.png). It's also available as stand-alone +module *g.gui.gmodeler*. + +The main Graphical Modeler menu contains options which enable the user +to fully control the model. Directly under the main menu one can find +toolbar with buttons (see figure below). There are options including (1) +Create new model, (2) Load model from file, (3) Save current model to +file, (4) Export model to image, (5) Export model to a +(Python/PyWPS/actinia) script, (6) Add command (GRASS module) to model, +(7) Add data to model, (8) Manually define relation between data and +commands, (9) Add loop/series to model, (10) Add comment to model, (11) +Redraw model canvas, (12) Validate model, (13) Run model, (14) Manage +model variables, (15) Model settings, (16) Show manual, (17) Quit +Graphical Modeler. + +![](g_gui_gmodeler_toolbar.png) +*Figure: Components of Graphical Modeler menu toolbar.* + +There is also a lower menu bar in the Graphical modeler dialog where one +can manage model items, visualize commands, add or manage model +variables, define default values and descriptions. The Script editor +dialog window allows seeing and exporting workflows as basic Python +scripts, as PyWPS scripts, or as actinia processes. The rightmost tab of +the bottom menu is automatically triggered when the model is activated +and shows all the steps of running GRASS modeler modules; in the case +some errors occur in the calculation process, they are are written at +that place. + +[](g_gui_gmodeler_lower_toolbar.png) +*Figure: Lower Graphical Modeler menu toolbar.* + +### Components of models + +The workflow is usually established from four types of diagrams. Input +and derived model data are usually represented with oval diagrams. This +type of model elements stores path to specific data on the user's disk. +It is possible to insert vector data, raster data, database tables, etc. +The type of data is clearly distinguishable in the model by its color. +Different model elements are shown in the figures below. + +- \(A\) raster data: + raster +- \(B\) relation: + relation +- \(C\) GRASS module: + module +- \(D\) loop: + loop +- \(E\) database table: + db +- \(F\) 3D raster data: + raster3D +- \(G\) vector data: + vector +- \(H\) disabled GRASS module: + module +- \(I\) comment: + comment + +[](g_gui_gmodeler_model_classification.png) +*Figure: A model to perform unsupervised classification using MLC +([i.maxlik](i.maxlik.md)) and SMAP ([i.smap](i.smap.md)).* + +Another example: + +[](g_gui_gmodeler_model_usle.png) +*Figure: A model to perform estimation of average annual soil loss +caused by sheet and rill erosion using The Universal Soil Loss +Equation.* + +Example as part of landslide prediction process: + +[](g_gui_gmodeler_model_landslides.png) +*Figure: A model to create parametric maps used by geologists to predict +landslides in the area of interest.* + +## EXAMPLE + +In this example the `zipcodes_wake` vector data and the +`elev_state_500m` raster data from the North Carolina sample dataset +(original +[raster](https://grass.osgeo.org/sampledata/north_carolina/nc_rast_geotiff.zip) +and +[vector](https://grass.osgeo.org/sampledata/north_carolina/nc_shape.zip) +data) are used to calculate average elevation for every zone. The +important part of the process is the Graphical Modeler, namely its +possibilities of process automation. + +### The workflow shown as a series of commands + +In the command console the procedure looks as follows: + +```bash +# input data import +r.import input=elev_state_500m.tif output=elevation +v.import input=zipcodes_wake.shp output=zipcodes_wake +# computation region settings +g.region vector=zipcodes_wake +# raster statistics (average values), upload to vector map table calculation +v.rast.stats -c map=zipcodes_wake raster=elevation column_prefix=rst method=average +# univariate statistics on selected table column for zipcode map calculation +v.db.univar map=zipcodes_wake column=rst_average +# conversion from vector to raster layer (due to result presentation) +v.to.rast input=zipcodes_wake output=zipcodes_avg use=attr attribute_column=rst_average +# display settings +r.colors -e map=zipcodes_avg color=bgyr +d.mon start=wx0 bgcolor=white +d.barscale style=arrow_ends color=black bgcolor=white fontsize=10 +d.rast map=zipcodes_avg bgcolor=white +d.vect map=zipcodes_wake type=boundary color=black +d.northarrow style=1a at=85.0,15.0 color=black fill_color=black width=0 fontsize=10 +d.legend raster=zipcodes_avg lines=50 thin=5 labelnum=5 color=black fontsize=10 +``` + +### Defining the workflow in the Graphical Modeler + +To start performing above steps as an automatic process with the +Graphical Modeler press the ![icon](icons/modeler-main.png) icon or type +*g.gui.gmodeler*. The simplest way of inserting elements is by adding +the complete GRASS command to the Command field in the GRASS command +dialog (see figure below). With full text search one can do faster +module hunting. Next, the label and the command can be added. In case +that only a module name is inserted, after pressing the *Enter* button, +the module dialog window is displayed and it is possible to set all of +the usual module options (parameters and flags). + +[](g_gui_gmodeler_dlg_module.png) +*Figure: Dialog for adding GRASS commands to model.* + +### Managing model parameters + +All used modules can be parameterized in the model. That causes +launching the dialog with input options for model after the model is +run. In this example, input layers (`zipcodes_wake` vector map and +`elev_state_500m` raster map) are parameterized. Parameterized elements +show their diagram border slightly thicker than those of unparameterized +elements. + +[](g_gui_gmodeler_parameter.png) +*Figure: Model parameter settings.* + +The final model, the list of all model items, and the Script editor +window with *Save* and *Run* option are shown in the figures below. + +[](g_gui_gmodeler_model_avg.png) +*Figure: A model to perform average statistics for zipcode zones.* + +[](g_gui_gmodeler_items.png) + +[](g_gui_gmodeler_python.png) +*Figure: Items with Script editor window.* + +For convenience, this model for the Graphical Modeler is also available +for download [here](g_gui_gmodeler_zipcodes_avg_elevation.gxm). + +The model is run by clicking the *Run* button ![run](icons/execute.png). +When all inputs are set, the results can be displayed as shown in the +next Figure: + +[](g_gui_gmodeler_avg_run.png) +[](g_gui_gmodeler_avg_map.png) +*Figure: Average elevation for ZIP codes using North Carolina sample +dataset as an automatic calculation performed by Graphical Modeler.* + +### Managing model properties + +When the user wants to run the model again with the same data or the +same names, it is necessary to use `--overwrite` option. It will cause +maps with identical names to be overwritten. Instead of setting it for +every module separately it is handy to change the Model Property +settings globally. This dialog includes also metadata settings, where +model name, model description and author(s) of the model can be +specified. + +[](g_gui_gmodeler_model_properties.png) +*Figure: Model properties.* + +### Defining variables + +Another useful trick is the possibility to set variables. Their content +can be used as a substitute for other items. Value of variables can be +values such as raster or vector data, integer, float, string value or +they may constitute some region, mapset, file or direction data type. +Then it is not necessary to set any parameters for input data. The +dialog with variable settings is automatically displayed after the model +is run. So, instead of model parameters (e.g. `r.import` a `v.import`, +see the Figure *[Run model dialog](g_gui_gmodeler_avg_run.png)* above) +there are `Variables`. + +[](g_gui_gmodeler_variables_run.png) +*Figure: Model with variable inputs.* + +The key point is the usage of `%` before the substituting variable and +settings in the `Variables` dialog. For example, in the case of a model +variable `raster` that points to an input file path and which value is +required to be used as one of inputs for a particular model, it should +be specified in the `Variables` dialog with its respective name +(`raster`), data type, default value and description. Then it should be +set in the module dialog as input called `%raster`. + +[](g_gui_gmodeler_variables.png) +*Figure: Example of raster file variable settings.* + +[](g_gui_gmodeler_variables_raster.png) +*Figure: Example of raster file variable usage.* + +### Saving the model file + +Finally, the model settings can be stored as a GRASS GIS Model file with +`*.gxm` extension. The advantage is that it can be shared as a reusable +workflow that may be run also by other users with different data. + +For example, this model can later be used to calculate the average +precipitation for every administrative region in Slovakia using the +`precip` raster data from [Slovakia precipitation +dataset](https://grass.osgeo.org/sampledata/slovakia3d_grass7.tar.gz) +and administration boundaries of Slovakia from [Slovak +Geoportal](https://www.geoportal.sk/sk/zbgis_smd/na-stiahnutie/) (only +with a few clicks). + +### Handling intermediate data + +There can be some data in a model that did not exist before the process +and that it is not worth it to maintain after the process executes. They +can be described as being `Intermediate` by single clicking using the +right mouse button, see figure below. All such data should be deleted +following model completion. The boundary of intermediate component is +dotted line. + +[](g_gui_gmodeler_intermediate_data.png) +*Figure: Usage and definition of intermediate data in model.* + +### Using the Script editor + +By using the Script editor in the Graphical Modeler, the user can add +Python code and then run it with *Run* button or just save it as a +Python script `*.py`. The result is shown in the Figure below: + +[](g_gui_gmodeler_python_code.png) +[](g_gui_gmodeler_python_code_result.png) +*Figure: Script editor in the wxGUI Graphical Modeler.* + +The second option in the *Script type* combobox exports a PyWPS script +instead of a basic Python one. A PyWPS process based on the model will +be generated then; for the PyWPS script, the *Run* button is disabled as +users are expected to include this script in their web processing +service and not to run it on itself. + +[](g_gui_gmodeler_pywps_code.png) +*Figure: Script editor in the wxGUI Graphical Modeler - set to PyWPS.* + +The third option in the *Script type* combobox exports an actinia +process chain (non-parameterized model) or an actinia template +(parameterized model). An actinia JSON based on the model will be +generated then; as for the PyWPS script, the *Run* button is disabled as +users are expected to include this JSON in their web processing service +and not to run it on itself. + +[](g_gui_gmodeler_actinia_code.png) +*Figure: Script editor in the wxGUI Graphical Modeler - set to actinia.* + +By default GRASS script package API is used +(`grass.script.core.run_command()`). This can be changed in the +settings. Alternatively also PyGRASS API is supported +(`grass.pygrass.modules.Module`). + +### Defining loops + +In the example below the [MODIS +MOD13Q1](https://e4ftl01.cr.usgs.gov/MOLT/MOD13Q1.006/) (NDVI) satellite +data products are used in a loop. The original data are stored as coded +integer values that need to be multiplied by the value `0.0001` to +represent real *ndvi values*. Moreover, GRASS GIS provides a predefined +color table called `ndvi` to represent *ndvi data*. In this case it is +not necessary to work with every image separately. +The Graphical Modeler is an appropriate tool to process data in an +effective way using loop and variables (`%map` for a particular MODIS +image in mapset and `%ndvi` for original data name suffix). After the +loop component is added to model, it is necessary to define series of +maps with required settings of map type, mapset, etc. + +[](g_gui_gmodeler_loop_dlg.png) +*Figure: MODIS data representation in GRASS GIS after Graphical Modeler +usage.* + +When the model is supplemented by all of modules, these modules should +be ticked in the boxes of loop dialog. The final model and its results +are shown below. + +[](g_gui_gmodeler_loop_final.png) +*Figure: Model with loop.* + +[](g_gui_gmodeler_modis_1o.png) +[](g_gui_gmodeler_modis_1.png) +[](g_gui_gmodeler_modis_2o.png) +[](g_gui_gmodeler_modis_2.png) +[](g_gui_gmodeler_modis_3o.png) +[](g_gui_gmodeler_modis_3.png) +*Figure: MODIS data representation in GRASS GIS after Graphical Modeler +usage.* + +The steps to enter in the command console of the Graphical Modeler would +be as follows: + +```bash +# note that the white space usage differs from the standard command line usage + +# rename original image with preselected suffix +g.rename raster = %map,%map.%ndvi +# convert integer values +r.mapcalc expression = %map = %map.%ndvi * 0.0001 +# set color table appropriate for nvdi data +r.colors = map = %map color = ndvi +``` + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +See also selected user models available from [GRASS Addons +repository](https://grass.osgeo.org/grass8/manuals/addons/). + +See also the +[wiki](https://grasswiki.osgeo.org/wiki/WxGUI_Graphical_Modeler) page +(especially various [video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI_Graphical_Modeler#Video_tutorials)). + +## AUTHORS + +Martin Landa, GeoForAll Lab, Czech Technical University in Prague, Czech +Republic +PyWPS support by Ondrej Pesek, GeoForAll Lab, Czech Technical University +in Prague, Czech Republic +Various manual improvements by Ludmila Furkevicova, Slovak University of +Technology in Bratislava, Slovak Republic diff --git a/gui/wxpython/iclass/g.gui.iclass.md b/gui/wxpython/iclass/g.gui.iclass.md new file mode 100644 index 00000000000..65ebdd82ca2 --- /dev/null +++ b/gui/wxpython/iclass/g.gui.iclass.md @@ -0,0 +1,77 @@ +## KEYWORDS + +[display](display.md), [GUI](topic_GUI.md), +[imagery](keywords.md#imagery), +[classification](keywords.md#classification), [supervised +classification](keywords.md#supervised-classification) + +## DESCRIPTION + +**Supervised Classification Tool** (wxIClass) is a *[wxGUI](wxGUI.md)* +component which allows the user to create training areas and generate +spectral signatures. The resulting signature file can be used as input +for *[i.maxlik](i.maxlik.md)* or as a seed signature file for +*[i.cluster](i.cluster.md)*. *WxIClass* can be launched from the Layer +Manager menu *Imagery → Classify image → Interactive input for +supervised classification* or via command line as *g.gui.iclass*. + +*wxIClass* currently allows you to: + +- create training areas (using customized *[vector + digitizer](wxGUI.vdigit.md)*) +- show histograms for each band and class (category) +- show coincidence plots for each band +- show raster cells that match training areas (within the number of + standard deviations specified) +- specify color of class +- write signature file +- import vector map +- export vector map with attribute table + + + +*wxIClass* performs the first pass in the GRASS two-pass supervised +image classification process; the GRASS module *[i.maxlik](i.maxlik.md)* +executes the second pass. Both programs must be run to generate a +classified map in GRASS raster format. + +*wxIClass* is an interactive program that allows the user to create +multiple training areas for multiple classes and calculate the spectral +signatures based on the cells that are within the training areas. During +this process the user will be shown histograms for each image band. The +user can also display the cells of the image bands which fall within a +user-specified number of standard deviations from the means in the +spectral signature. By doing this, the user can see how much of the +image is likely to be put into the class associated with the signature. + +*wxIClass* can also import training areas defined in a vector layer. In +that case the program expects the vector layer to have the following +columns defined: + +- cat: category value +- class: a string with the class name +- color: a color defined using format "RRR:GGG:BBB" + +The spectral signatures are composed of region means and covariance +matrices. These region means and covariance matrices are used in the +second pass (*[i.maxlik](i.maxlik.md)*) to classify the image. + +Alternatively, the spectral signatures generated by *wxIClass* can be +used for seed means for the clusters in *[i.cluster](i.cluster.md)*. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md), +[Interactive Scatter Plot Tool](wxGUI.iscatt.md)* + +See also user [wiki](https://grasswiki.osgeo.org/wiki/WxIClass) page and +[development](https://trac.osgeo.org/grass/wiki/wxGUIDevelopment/wxIClass) +page. + +## AUTHORS + +Anna Kratochvilova, [Czech Technical University in +Prague](https://www.cvut.cz), Czech Republic +Vaclav Petras, [Czech Technical University in +Prague](https://www.cvut.cz), Czech Republic diff --git a/gui/wxpython/image2target/g.gui.image2target.md b/gui/wxpython/image2target/g.gui.image2target.md new file mode 100644 index 00000000000..9ff5a449e74 --- /dev/null +++ b/gui/wxpython/image2target/g.gui.image2target.md @@ -0,0 +1,261 @@ +## DESCRIPTION + +The **GCP Manager** is a *[wxGUI](wxGUI.md)* extension which allows the +user to create, edit, and manage Ground Control Points. It is available +from the menu "File \| Manage Ground Control Points". + +The **GCP Manager** provides an interactive graphical interface to +manage and analyze Ground Control Points. A backup copy of the initial +POINTS file is always maintained and updated only on request (Save GCPs +to POINTS file). This guarantees that accidental changes are not +permanent and can be undone by reloading the Ground Control Points. + +The GCP Manager must be started in the target project, not in the source +project (project used to be called location). + +The GCP Manager is structured into three panels: + +- The topmost panel shows a list of Ground Control Points. Tools to + manipulate and analyze GCPs are provided in the toolbar. This panel + can be moved out of the GCP manager window by either dragging with the + caption or by clicking on the pin button on the right in the caption. + This panel can also be placed below the map displays by dragging. +- The two panels in the lower part are used for map and GCP display, the + left pane showing a map from the source project and the right pane + showing a reference map from the target project. Numbered Ground + Control Points are shown on both map displays. + +### Components of the GCP Manager + +GCP Manager + +*Toolbars* + +Two toolbars are provided with the GCP Manager, one for managing the map +displays and one for managing the GCP list. + +*List of ground control points* + +The list of Ground Control Points can be sorted by clicking on a column +header. Clicking on a column header will sort the GCPs ascending, a +second click on the same column will sort the GCPs descending. Overall +RMS error and individual RMS errors of all points are often improved if +the GCP with the highest RMS error is adjusted. Individual coordinates +can be edited by double-clicking on a row. + +The first column holds a checkbox and displays the point number. A GCP +is only used for RMS error calculation and georectification if its +checkbox on the left is checked. Uncheck to deactivate a GCP (mark as +unused GCP). + +*Two panels for map display* + +The left panel is used to display a map from the source project, the +right panel to display a map from the target project. Zooming in and out +is always possible with the mouse wheel and done for each map canvas +separately. + +GCPs are displayed in different colors, depending on whether a GCP has a +high RMS error, is currently unused or is currently selected. +Optionally, currently unused GCPs are not shown on the map display. + +*Statusbar* + +At the bottom of the GCP Manager is a statusbar providing several +functions. The default is set to *Go to GCP No.* (see also below). +Typing a number or using the up/down arrows will center the maps on the +given GCP, useful with a high zoom. + +#### GCP Map Display Toolbar + +![icon](icons/show.png)  *Display map* +Displays maps for source and target canvas and re-renders any layers +that have changed since the last time the display was updated. + +![icon](icons/layer-redraw.png)  *Re-render map* +Re-renders both source and target canvas regardless of whether they have +changed or not. + +![icon](icons/erase.png)  *Erase display* +Erases both source and target canvas to a white background. + +![icon](icons/gcp-create.png)  *Define GCP (Ground Control Points)* +On left mouse click, coordinates are defined for the currently selected +GCP. + +![icon](icons/pan.png)  *Pan* +Interactive selection of a new center of view in the active display +monitor. Drag the pan cursor while pressing the left mouse button to +pan. Alternatively left-click on the new center. Panning changes the +location of the region displayed but not the size of the area displayed +or the resolution. + +![icon](icons/zoom-in.png)  *Zoom in* +Interactive zooming with the mouse in the active map canvas (source or +target). Drawing a box or just a left click with the mouse and zoom-in +cursor causes the display to zoom in so that the area defined by the box +fills the display. The map resolution is not changed. Clicking with the +zoom-in cursor causes the display to zoom in by 30%, centered on the +point where the mouse is clicked. Zooming changes the display region +extents (both size and location of area displayed). + +![icon](icons/zoom-out.png)  *Zoom out* +Interactive zooming with the mouse in the active map canvas (source or +target). Drawing a box or just a left click with the mouse and zoom-out +cursor causes the display to zoom out so that the area displayed shrinks +to fill the area defined by the box. The map resolution is not changed. +Clicking with the zoom-out cursor causes the display to zoom out by 30%, +centered on the point where the mouse is clicked. Zooming changes the +display region extents (both size and location of area displayed). + +![icon](icons/zoom-more.png)  *Adjust display zoom* +Source and target display are adjusted by using the current GCPs for +coordinate transformation: + +*Adjust source display to target display* +The extents of the source display are adjusted to the current extents of +the target display. + +*Adjust target display to source display* +The extents of the source display are adjusted to the current extents of +the target display. + +*Set active map canvas* +Sets the currently active map canvas (source or target). Click to set +active map canvas for *Return to previous zoom* or *Zoom to extent of +currently displayed map*. Alternatively, move the mouse over the map +canvas to be used as active canvas. + +![icon](icons/zoom-last.png)  *Return to previous zoom* +Returns to the previous zoom extent. Up to 10 levels of zoom back are +maintained. + +![icon](icons/zoom-extent.png)  *Zoom to extent of currently displayed map* +Zoom to the extent of the currently displayed map in the active map +canvas (source or target). + +![icon](icons/settings.png)  *Settings* +Shows a settings dialog for GCP management and display: + +*Symbology* +Settings for map and GCP display: + +*Highlight highest RMS error only* +Only the GCP with the highest RMS error will be displayed in a different +colour, both in the list of GCPs and the GCP Map Display. + +*Factor for RMS error threshold = M + SD \* factor:* +All GCPs with an RMS error larger than mean RMS + RMS standard deviation +\* this factor will be displayed in a different colour, both in the list +of GCPs and the GCP Map Display. As a rule of thumb, GCPs with an RMS +error larger than *M + SD \* 2* are most probably wrong. GCPs with an +RMS error larger than *M + SD \* 1* are worth closer inspection. This +option is only available if *Highlight highest RMS error only* is +unchecked. + +*Color* +Set the color for GCPs on the GCP Map Display. + +*Color for high RMS error* +Set the color for GCPs with a high RMS error on the GCP Map Display. + +*Color for selected GCP* +Set the color for the currently selected GCP on the GCP Map Display. + +*Show unused GCPs* +If unchecked, unused GCPs will not be shown on the GCP Map Display. + +*Color for unused GCPs* +Set the color for unused GCPs on the GCP Map Display. + +*Symbol size* +Set the symbol size for GCPs on the GCP Map Display. + +*Line width* +Set the line width for GCPs on the GCP Map Display. + +*Select source map to display* +Select a source map for the left pane of the GCP Map Display. + +*Select target map to display* +Select a target map for the right pane of the GCP Map Display. + +*Rectification* +Settings for georectification: + +*Select rectification method* +Set the polynomial order for georectification. This order will also be +used for RMS error calculation. + +*Clip to computational region in target project* +Clip raster maps to the current computational region in the target +project when georectifying. + +*Extension for output maps* +Change the extension for output map names when doing the actual +georectification. + +![icon](icons/help.png)  *Show Help* +Show help page for the GCP Manager. + +![icon](icons/quit.png)  *Quit* +Quit the GCP Manager. + +#### Toolbar for the GCP list + +![icon](icons/gcp-save.png)  *Save GCPs to POINTS file* +The current list of GCPs is saved to the imagery group's POINTS file and +to a backup copy. + +![icon](icons/gcp-add.png)  *Add new GCP* +Adds a new Ground Control Point to the list and selects it for editing. + +![icon](icons/gcp-delete.png)  *Delete selected GCP* +Deletes the currently selected GCP from the list. + +![icon](icons/gcp-remove.png)  *Clear selected GCP* +Resets all coordinates of the currently selected GCP to 0 (zero). + +![icon](icons/reload.png)  *Reload GCPs from POINTS file* +Reloads GCPs from the imagery group's POINTS file. + +![icon](icons/gcp-rms.png)  *Recalculate RMS error* +Recalculates forward and backward RMS error for all GCP marked for use +(activated checkbox in first row). + +![icon](icons/georectify.png)  *Georectify* +Uses *[i.rectify](i.rectify.md)* to georectify all images in the source +imagery group. + +#### GCP Map Display Statusbar + +The GCP map display statusbar is similar to the statusbar in the regular +GRASS GIS map display with two differences, *Go to* has been replaced +with *Go to GCP No.* and *Projection* has been replaced with *RMS +error*. + +If *Go to GCP No.* is selected, a GCP number can be given in the left +side of the statusbar and the source and target map canvas will be +centered on the given GCP. Clicking on the map canvas will update +coordinates for this GCP. + +If *RMS error* is selected, the overall forward and backward RMS error +is displayed. + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +*[i.rectify](i.rectify.md), [m.transform](m.transform.md), +[v.rectify](v.rectify.md)* + +See also [video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI/Video_tutorials#Georectifier) +on GRASS Wiki. + +## AUTHORS + +Markus Metz + +*Based on the Georectifier (GRASS 6.4.0)* by Michael Barton +Martin Landa, Czech Technical University in Prague, Czech Republic diff --git a/gui/wxpython/mapswipe/g.gui.mapswipe.md b/gui/wxpython/mapswipe/g.gui.mapswipe.md new file mode 100644 index 00000000000..409c32204a2 --- /dev/null +++ b/gui/wxpython/mapswipe/g.gui.mapswipe.md @@ -0,0 +1,44 @@ +## DESCRIPTION + +The **Map Swipe** is a *[wxGUI](wxGUI.md)* component which allows the +user to interactively compare two raster maps of the same area by +revealing different parts of the raster maps. It is useful e.g. for +comparing raster maps from different time periods. Map Swipe can be +launched from the menu `File -> Map Swipe`. + +Map Swipe allows you to: + +- switch orientation of the swipe line (horizontal or vertical) +- zooming, panning +- automatically load maps when opening Map Swipe with two selected + raster maps in Layer Manager +- compare 2 raster maps or load different combinations of raster and + vector maps and set transparency (advanced mode) +- save display to graphics file +- display text labels with map names +- choose between 'swipe' mode (default) and 'mirror' mode (synchronized + maps displayed side by side) +- change the appearance of cursor in 'mirror' mode (available in Map + Swipe settings) + + +Pre and post disaster images of the tsunami in Japan in 2011. The upper +MODIS image taken on February 26, 2011, shows the coastline under normal +conditions while the lower MODIS image on March 13, 2011, shows a clear +view of tsunami flooding along the coastline. Water, black and dark blue +in these false-color images, still covers the ground as much as five +kilometers (three miles) from the coast. Source: [Earth +Observatory/NASA](https://earthobservatory.nasa.gov/images/49634/tsunami-flooding-near-sendai-japan) + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +See also the user +[wiki](https://grasswiki.osgeo.org/wiki/WxGUI_Map_Swipe) page. + +## AUTHOR + +Anna Kratochvilova, [Czech Technical University in +Prague](https://www.cvut.cz), Czech Republic diff --git a/gui/wxpython/photo2image/g.gui.photo2image.md b/gui/wxpython/photo2image/g.gui.photo2image.md new file mode 100644 index 00000000000..69eb0a81b43 --- /dev/null +++ b/gui/wxpython/photo2image/g.gui.photo2image.md @@ -0,0 +1,58 @@ +## DESCRIPTION + +This module is based on **g.gui.gcp**, the GCP manager of GRASS GIS. It +is part of i.ortho.photo suite. + +The aim of this module is to give absolute location values to the +fiducial points present (in number of 4 or 8) in a *scanned* aerial +photo. + +This is necessary as (manual) scanning introduces distortions, rotations +and also may not be limited to scan the boundary of the photo itself. It +is thus necessary to give to each fiducial the exact coordinates in mm +as given by the aerial photographic instrument design, which is unique +per camera. + +This module requires you to have made a group with your aerial photo +**(i.group)**, a camera description file **(i.ortho.target)** and use +them to launch the module. Additional requirements are the order of +rectification (1 if no of Fiducials is 4, 2 if no of Fiducials is 8) and +an extension file (if not given, defaults to \\filename_ip2i_out) + +An example for project **imagery60**: + +```bash +g.gui.photo2image group=aerial@PERMANENT raster=gs13.1@PERMANENT camera=gscamera order=2 extension=try --o +``` + +### Screenshot of g.gui.photo2image + +
+ +[Screenshot of g.gui.photo2image](wxGUI_iphoto2image_frame.jpg) +*Figure: Screenshot of g.gui.photo2image* + +
+ +## For a detailed operation manual please read + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +See also [video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI/Video_tutorials#Georectifier) +on GRASS Wiki. + +## SEE ALSO + +*[i.ortho.photo](i.ortho.photo.md), [i.group](i.group.md), +[i.ortho.camera](i.ortho.camera.md), +[i.ortho.target](i.ortho.target.md), [i.rectify](i.rectify.md), +[m.transform](m.transform.md), [v.rectify](v.rectify.md)* + +## AUTHORS + +Markus Metz + +*Based on the Georectifier (GRASS 6.4.0)* by Michael Barton +Martin Landa, Czech Technical University in Prague, Czech Republic diff --git a/gui/wxpython/psmap/g.gui.psmap.md b/gui/wxpython/psmap/g.gui.psmap.md new file mode 100644 index 00000000000..d7c6e5a52c9 --- /dev/null +++ b/gui/wxpython/psmap/g.gui.psmap.md @@ -0,0 +1,193 @@ +## DESCRIPTION + +**wxGUI Cartographic Composer** also called *wx.psmap* is a +*[wxGUI](wxGUI.md)* extension which allows the user to create +interactively hardcopy map outputs. This tool generates +*[ps.map](ps.map.md)* configuration file and then runs +*[ps.map](ps.map.md)* to create PostScript output. There are two modes - +*Draft mode* for map composing and *Preview mode* (requires [Python +Imaging Library](http://www.pythonware.com/products/pil/)) to see how +the result will look like. In draft mode map features (like legend or +scalebar) are represented by a colored rectangle with a label. + +Possible output files: + +- *[ps.map](ps.map.md)* instructions file +- PostScript/EPS file +- PDF (using ps2pdf) + + + +Cartographic Composer enables to load in saved instructions file. +Loading instruction files created by Cartographic Composer is more +robust, as opposed to loading files created manually. + +Currently supported *[ps.map](ps.map.md)* instructions: + +- paper +- maploc +- scale +- border +- raster +- colortable +- vpoints +- vlines +- vareas +- vlegend +- text +- scalebar +- mapinfo +- point +- line +- rectangle +- labels + +### CARTOGRAPHIC COMPOSER TOOLBAR + +![icon](icons/script-save.png)  *Generate instructions file* +Generates and saves text file with mapping instructions. + +![icon](icons/script-load.png)  *Load instructions file* +Load text file with mapping instructions. + +![icon](icons/page-settings.png)  *Page setup* +Specify paper size, margins and orientation. + +![icon](icons/pointer.png)  *Pointer* +Select object on the paper by clicking, drag the cursor while pressing +the left mouse button to move it or resize object (currently only map +frame) by clicking on a small black box in its bottom right corner. +Double click to show object properties dialog + +![icon](icons/pan.png)  *Pan* +Drag the pan cursor while pressing the left mouse button to move your +view. + +![icon](icons/zoom-in.png)  *Zoom in* +Interactive zooming with the mouse in both draft and preview mode. +Drawing a box or just a left click with the mouse and zoom-in cursor +causes the display to zoom in so that the area defined by the box fills +the display. + +![icon](icons/zoom-out.png)  *Zoom out* +Interactive zooming with the mouse in both draft and preview mode. +Drawing a box or just a left click with the mouse and zoom-out cursor +causes the display to zoom out so that the area displayed shrinks to +fill the area defined by the box. + +![icon](icons/zoom-extent.png)  *Zoom to page* +Zoom to display the entire page + +![icon](icons/layer-add.png)  *Map frame* +Click and drag to place map frame. If map frame is already drawn, open a +dialog to set its properties. + +![icon](icons/layer-raster-add.png)  *Raster map* +Shows a dialog to add or change the raster map. + +![icon](icons/layer-vector-add.png)  *Vector map* +Shows a dialog to add or change current vector maps and their +properties: + +*Data selection* +Select data to draw: + +*Feature type* +Select which data type to draw. In case of point data, points or +centroids can be drawn, in case of line data, lines or boundaries. + +*Layer selection* +Select layer and limit data by a SQL query or chose only certain +categories. + +*Mask* +Whether to use mask or not. + +*Colors* +Color settings: + +*Outline* +Select outline color and width in points. In case of lines, outline +means highlighting. + +*Fill* +Select fill color, one color for all vector elements or color from rgb +column. + +*Size and style* +Sets size, style, symbols, pattern; depends on data type: + +*Symbology* +Available for point data. Choose symbol or EPS file to draw points with. + +*Line style* +Available for line data. Select line style (solid, dashed, ...) and the +look of the ends of the line (butt, round, ...) + +*Pattern* +Available for areas. Choose pattern file and set the width of the +pattern. + +*Size* +Available for point data. Choose size (number of times larger than the +size in the icon file) as a single value or take the size from a map +table column. + +*Rotation* +Available for point data. Rotate symbols counterclockwise with the given +value or with the value from a map table column + +*Width* +Available for line data. Set line width in points or take the value from +a map table column. + +![icon](icons/layer-more.png)  *Add overlays* +Add overlays: vector labels, grid (not yet implemented) + +![icon](icons/layer-label-add.png)  *Add labels* +Add vector labels created beforehand by v.label module. + +![icon](icons/overlay-add.png)  *Add map elements* +Add map elements: legend, scalebar, map info, text + +![icon](icons/legend-add.png)  *Add legend* +Add raster or vector legend or edit their properties. + +![icon](icons/map-info.png)  *Add map info* +Add information about region, grid and scale or edit map info +properties. + +![icon](icons/scalebar-add.png)  *Add scalebar* +Add scalebar or edit its properties. + +![icon](icons/text-add.png)  *Add text* +Add text label. + +![icon](icons/layer-remove.png)  *Remove selected element* +Select an object and remove it. Pressing Delete key does the same. + +![icon](icons/execute.png)  *Show preview* +Generates output and switches to Preview mode to see the result. Be +patient, it can take a while. + +![icon](icons/ps-export.png)  *Generate hardcopy map output in PS* +Generates hardcopy map output in PostScript/EPS file. + +![icon](icons/pdf-export.png)  *Generate hardcopy map output in PDF* +Generates hardcopy map output in PDF using ps2pdf or [Ghostscript +gswin32c/gswin64c](https://www.ghostscript.com/releases/gsdnld.html) (OS +MS Windows platform only). + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +See also +[wiki](https://grasswiki.osgeo.org/wiki/WxGUI_Cartographic_Composer) +page. + +## AUTHOR + +Anna Kratochvilova, Czech Technical University in Prague, Czech Republic +(bachelor's final project 2011, mentor: Martin Landa) diff --git a/gui/wxpython/rdigit/g.gui.rdigit.md b/gui/wxpython/rdigit/g.gui.rdigit.md new file mode 100644 index 00000000000..a3361a64e38 --- /dev/null +++ b/gui/wxpython/rdigit/g.gui.rdigit.md @@ -0,0 +1,86 @@ +## KEYWORDS + +[display](display.md), [GUI](topic_GUI.md), +[raster](keywords.md#raster), [editing](keywords.md#editing), +[digitizer](keywords.md#digitizer) + +## DESCRIPTION + +**Raster Digitizer** is a simple tool to quickly draw lines, areas, and +circles and save these features in a raster map. It is accessible from +the Map Display toolbar (from the combo box on the right). + +*Raster Digitizer* currently allows you to: + +- draw polygons, lines and points +- set category value of the feature you are drawing +- set feature width (width of currently digitized line or diameter of a + digitized point in map units) +- create a new raster from scratch or from an already existing raster +- undo edits and save edits before leaving the digitizer + +The typical workflow includes these steps: + +1. Set computational region as needed. +2. Switch to Raster Digitizer and select a map to create. Select either + a new raster or create a new raster from existing raster, also + select raster type (CELL, FCELL, DCELL) +3. Specify category value and width *before* drawing a feature +4. Specify digitizing tool (area, line, point) +5. Start digitizing and when you want to finish area or line, *use + right click* +6. Change color of temporary overlay depending on your needs +7. Set different category and repeat +8. At any point you can use *Undo* or *Save* +9. If existing raster is used for the new raster, digitized areas will + respect the color table, but you can always set different color + table. + +## NOTES + +Raster Digitizer respects computational region including the currently +set resolution. + +## EXAMPLES + +In the following figures we start with elev_lid792_1m raster map in +North carolina sample dataset and digitize two buildings, one +rectangular and one with circular footprint. Both buildings have the +roof level at 130 m. We set the width when digitizing the point to 50 +meters which results in the building having 50 m in diameter. When we +are done with digitizing, we save the result and explore cast shadows of +the buildings with [r.sun](r.sun.md) module: + +```bash +g.region raster=elev_lid792_1m +# now create elev_edited raster by digitizing and save +r.slope.aspect elevation=elev_edited slope=elev_slope aspect=elev_aspect +r.sun elevation=elev_edited aspect=elev_aspect slope=elev_slope beam_rad=beam day=172 time=6 +``` + +
+ +[](wxGUI_rdigit_step1.png) +[](wxGUI_rdigit_step2.png) +[](wxGUI_rdigit_step3.png) +[](wxGUI_rdigit_step4.png) +[](wxGUI_rdigit_step5.png) +*Figure: Steps to digitize new buildings on elev_lid792_1m raster map.* + +
+ +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md), +[r.in.poly](r.in.poly.md) (backend of digitizer), +[g.gui.vdigit](g.gui.vdigit.md)* + +## AUTHORS + +Anna Petrasova, NCSU GeoForALL Laboratory +Tomas Zigo (standalone module) diff --git a/gui/wxpython/rlisetup/g.gui.rlisetup.md b/gui/wxpython/rlisetup/g.gui.rlisetup.md new file mode 100644 index 00000000000..a93ee4a3fe0 --- /dev/null +++ b/gui/wxpython/rlisetup/g.gui.rlisetup.md @@ -0,0 +1,263 @@ +## DESCRIPTION + +The **g.gui.rlisetup** is a *[wxGUI](wxGUI.md)* component which allows +the user to create a configuration file for the analytical *r.li* +modules. For a general introduction, see the [r.li](r.li.md) overview. +The configurations are raster map independent, it means that you can use +a file created on a raster map for analyze any other you have. +The program is completely interactive and uses a GUI to help you in your +choices. + +### Analysis methods + +Definition of creation of sampling area: + +- Whole map layer: use entire area selected above, +- Regions: select one to many subareas via mouse, +- Sample units: automated selection of sampling area (for details see + below) + - Random nonoverlapping, + - Systematic contiguous, + - Systematic noncontiguous, + - Stratified random, + - Centered over sites (vector points). +- Moving window: rectangular or circular with size + +![Sampling area definitions](g_gui_rlisetup_sample_areas.png) + +Definition of region for analysis: + +- Whole map layer: entire map (current region), +- Keyboard setting: based on keyboard selection for region definition, +- Draw the sampling frame: based on interactive region selection via + mouse. + +### Usage details + +The startup window shows your configuration files, you can: + +**TODO: description below needs further updates** + +1. ***View/Edit*** (Load a file) from the shown list: the configuration + is shown in a small text editor window. Configuration files are + saved in the folder `C:\Users\userxy\AppData\Roaming\GRASS8\r.li\` + (MS-Windows) or `$HOME/.r.li/` (GNU/Linux) (the file name can be + defined by the user). The output or an analysis can either be a new + raster map (in case of using a "moving window" analysis) or be an + ASCII text file (when not performing a "moving window" analysis) + containing the result. Such text file will be saved in the folder + `C:\Users\userxy\AppData\Roaming\GRASS8\r.li\output\` (MS-Windows) + or `$HOME/.grass8/r.li/output/` (GNU/Linux). + All dimensions are percentages of raster rows or columns. +2. ***Create*** a new configuration file: used for creating a new + configuration file in an interactive way, in three steps: + 1. Choose file name and maps to use for setting: + - *Name for new configuration file*(required): the name of new + configuration file + - *Raster map name to use to select areas* (required): the name + of raster map used for selecting sampling areas + - *Vector map to overlay* (optional): name of a vector map used + for selecting sampling areas + 2. Set the sampling frame. The sample frame is a rectangular area + which contains all the areas to analyze. It can be defined in + three ways: + - *Whole map layer*: the sample frame is the whole map + - *Keyboard setting*: the user enters the coordinates in cells + of upper left corner of sampling frame and its length in rows + and columns. + - *Draw the sample frame*: the user draws the sample frame on + map using mouse. + 3. Set the sample areas. The sample areas are simply the areas to + analyze. They can be defined in five ways (see the picture + below): + - *Whole map layer*: the sample area is the whole sample frame + - *Regions*: the user enters the number of areas and then draws + them using mouse. + - *Sample units*: they are areas of rectangular or circular + shape. The user can define them using keyboard or mouse. + - keyboard: the user define the shape of sample unists and + their disposition: + - *Random non overlapping*: the user specifies the number of + sample units and they are placed in a random way at + runtime. It is guaranteed that the areas do not intersect + themselves. + - *Systematic contiguous*: the defined sample is placed + covering the sample frame, side by side across rows. + - *Systematic non contiguous*: the same as above, but here + ever rectangle is spaced from another by a specified + number of cells. + - *Stratified random*: the sample frame is divided in *n* + strats of rows and *m* strats of columns (*n* and *m* are + given by user), then the specified number of sample areas + are placed in a random way, one for every *m\*n* areas + defined by strats. + - *Centered over sites*: the sample areas are placed into + sample frame centering them on points in site file. + - mouse: the user chooses the shape and then draws the + specified number of sample areas on map. + - *Moving Window:* the user defines a rectangular or circular + area, it is moved over all the raster increasing only of a + cell for every move(in columns if possible, if not in rows). + It produces a new raster containing the result of all + analysis. + - *Select areas from the overlaid vector map*: the sample areas + are defined by the vector map selected above. For every cat in + vector map, the procedure prompts the user if they want to + include it as sample area. The resulting configuration file + can be used only with the specified raster map, and the + procedure can be used only if whole map layer is selected as + sampling frame. +3. ***Remove a file*** the selected file is deleted from the available + configuration files. +4. ***Help***: open this help text. +5. ***Close*** module window. + +## NOTES + +Configuration files are raster map independent because areas are saved +using relative coordinates. + +Screenshots of the wizard window frames: + + ++++ + + + + + + + + + + + + + + + + + + +
 
+g.gui.rlisetup: First frame of wizard for selecting
+existing configuration files or creating a new one		 
+g.gui.rlisetup: Frame for selecting maps
 
+g.gui.rlisetup: Frame for inserting sampling areas		 
+g.gui.rlisetup: Frame for defining rectangular moving +window
 
+g.gui.rlisetup: Frame for defining circular moving window		 
+g.gui.rlisetup: Frame for choosing the sampling frame with +keyboard
 
+g.gui.rlisetup: Frame for drawing the sampling frame		 
+g.gui.rlisetup: Summary frame before saving
+ +## EXAMPLES + +### Moving window analysis on full region + +*TODO: update examples to new g.gui.rlisetup dialog:* + +Example for a 7x7 moving window analysis on full region, the output is a +raster map: + +Click on "New", then: + +- Configuration file name: "movwindow7" +- Raster map name to use to select areas: "forests" + +1\. Setup sampling frame: + +- Define a sampling frame (region for analysis): "Whole map layer", then + "OK" + +2\. Setup sampling frame + +- Define sampling areas: "Moving window", then "OK" +- Then click on "Use keyboard to define moving window dimension" + +Select type of shape: + +- \[x\] Rectangular +- Width size (in cells)?: "7" +- Height size (in cells)?: "7" +- Then "Save settings" + +3\. Save settings: click on button +(4.) Close + +Now an anaysis can be performed using one of the analytical modules, +e.g. + +```bash +g.region raster=forests -p +r.li.patchdensity input=forests conf=movwindow7 output=forests_p_dens7 +r.univar forests_p_dens7 +``` + +The result is the new raster map "forests_p_dens7" which shows (in this +example) the patch density of the forest areas. +See the respective modules for further examples. + +### Whole region analysis + +Example for a whole region analysis, the output is a text file: Click on +"New", then: + +- Configuration file name: "whole_region" +- Raster map name to use to select areas: "lsat7_2000_40" + +1\. Setup sampling frame: + +- Define a sampling frame (region for analysis): "Whole map layer", then + "OK" + +2\. Setup sampling frame + +- Define sampling areas: "Whole map layer", then "OK" + +3\. Save settings: click on button +(4.) Close + +Now an anaysis can be performed using one of the analytical modules, +e.g. + +```bash +g.region raster=lsat7_2002_40 -p +r.li.shannon input=lsat7_2000_40 conf=whole_region output=lsat7_2000_40_shannon +``` + +The result is the new text file "forests_p_dens7" (stored in folder +`$HOME/.r.li/output/`. +See the respective modules for further examples. + +## REFERENCES + +McGarigal, K., and B. J. Marks. 1995. FRAGSTATS: spatial pattern +analysis program for quantifying landscape structure. USDA For. Serv. +Gen. Tech. Rep. PNW-351. ([PDF](https://doi.org/10.2737/PNW-GTR-351)) + +## SEE ALSO + +*[r.li](r.li.md) (package overview), [r.li.daemon](r.li.daemon.md)* + +*[Old r.le suite +manual](https://grass.osgeo.org/gdp/landscape/r_le_manual5.pdf) (1992)* + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +## AUTHORS + +Luca Delucchi +Rewritten from *r.li.setup* by Claudio Porta and Lucio Davide Spano diff --git a/gui/wxpython/timeline/g.gui.timeline.md b/gui/wxpython/timeline/g.gui.timeline.md new file mode 100644 index 00000000000..584e04986da --- /dev/null +++ b/gui/wxpython/timeline/g.gui.timeline.md @@ -0,0 +1,30 @@ +## DESCRIPTION + +The **Timeline Tool** is a *[wxGUI](wxGUI.md)* component which allows +the user to compare the extents of temporal datasets (strds, stvds, +str3ds) in a plot. + +Supported features: + +- temporal datasets with interval/point and absolute/relative time +- 2D plots - temporal extent +- 3D plots - spatio-temporal extent (matplotlib \>= 1.0.0) +- pop-up annotations with basic metadata + + + +## NOTES + +*g.gui.timeline* requires the Python plotting library +[Matplotlib](https://matplotlib.org/). + +## SEE ALSO + +*[Temporal data processing](temporal.md), [wxGUI](wxGUI.md), [wxGUI +components](wxGUI.components.md)* + +## AUTHOR + +Anna Kratochvilova, [Czech Technical University in +Prague](https://www.cvut.cz), Czech Republic diff --git a/gui/wxpython/tplot/g.gui.tplot.md b/gui/wxpython/tplot/g.gui.tplot.md new file mode 100644 index 00000000000..e44fd6ef847 --- /dev/null +++ b/gui/wxpython/tplot/g.gui.tplot.md @@ -0,0 +1,91 @@ +## DESCRIPTION + +The **Temporal Plot Tool** is a *[wxGUI](wxGUI.md)* component that +queries and plots the values of a point, defined by a coordinate pair, +in one or more temporal datasets (strds, stvds, str3ds). + +Supported features: + +- temporal datasets with interval/point and absolute/relative time, + +- show simple linear regression model line with calculated formula + + ```bash + y = a + b*x (y is dependent variable, a is intercept, b is slope, x is explanatory variable) + ``` + + and + + ```bash + r-squared (parameter of goodness-of-fit measure for linear regression model) + ``` + +- pop-up annotations with values information, + +- query and plot multiple points via the command line, + +- zoom and pan, + +- change labels to x and y axes, + +- add title to the plot, and + +- export the time series values to a CSV file (x axis data has date time + string format, if you want to use for calculating simple regression + model in the [R environment](https://www.r-project.org/), + [LibreOffice](https://www.libreoffice.org/) etc., you will obtain a + different calculated formula + + ```bash + y = a + b*x + ``` + + because these software packages use a reference date other than the + UNIX Epoch time (00:00:00 UTC on 1 January 1970)). + +
+ +[](g_gui_tplot_labels.png) +*Figure: Temporal Plot Tool* + +
+ +To optionally add a title to the temporal plot and/or change the x and y +axes labels, first type the desired text and then click *Draw* as showed +below. + +
+ +[g.gui.tplot add title and axes labels](g_gui_tplot_labels.png) +*Figure: Add title and labels to a time series plot* + +
+ +To export the time series data to a text file (date and data values), +type a name for the file and click *Draw* again. Optionally, set the +check-box to print headers, as well. + +
+ +[g.gui.tplot export time series as csv file](g_gui_tplot_export_csv.png) +*Figure: Export time series values to a text file* + +
+ +## NOTES + +*g.gui.tplot* requires the Python plotting library +[Matplotlib](https://matplotlib.org/). + +## SEE ALSO + +*[Temporal data processing](temporal.md), [wxGUI](wxGUI.md), [wxGUI +components](wxGUI.components.md)* + +## AUTHOR + +Luca Delucchi, [Fondazione Edmund Mach](http://www.gis.cri.fmach.it), +Italy diff --git a/gui/wxpython/vdigit/g.gui.vdigit.md b/gui/wxpython/vdigit/g.gui.vdigit.md new file mode 100644 index 00000000000..b048e20081a --- /dev/null +++ b/gui/wxpython/vdigit/g.gui.vdigit.md @@ -0,0 +1,249 @@ +## DESCRIPTION + +The **vector digitizer** is a *[wxGUI](wxGUI.md)* component intended for +interactive editing and digitizing vector maps (see +*[v.edit](v.edit.md)* for non-interactive vector editing GRASS +capabilities). + +Note that only vector maps stored or generated in the *current* mapset +can be opened for editing. + +The digitizer allows editing of 2D vector features (points, lines, +centroids, boundaries, and areas). + +Vector features can be selected by mouse (bounding box or simply by +mouse click, see select threshold in *Settings→General→Select +threshold*), or by query (eg. by line length, see *Settings→Query +Tool*). + +### STARTING THE DIGITIZER + +The vector digitizer can be launched from Map Display toolbar by +selecting "Digitize" from *Tools* combobox. Vector map is selectable for +editing from Digitizer toolbar ("Select vector map" combobox, note that +only vector maps from the current layer tree in Layer Manager are +listed). The vector digitizer can alternatively be activated from the +contextual menu in the Layer Manager by selecting "Start editing" on +selected vector map in the layer tree, or directly from the Layer +Manager toolbar ![icon](icons/edit.png). The vector digitizer also can +also be launched from the command line as a stand-alone application +*g.gui.vdigit*. + +### CREATING A NEW VECTOR MAP + +A new vector map can be easily created from the digitizer toolbar by +selecting "New vector map" in "Select vector map" combobox. A new vector +map is created, added to the current layer tree in Layer Manager and +opened for editing. "Select vector map" combobox in the digitizer +toolbar also allows easily switching between vector maps to be edited. + +### EDITING AN EXISTING VECTOR MAP + +An existing vector map selected in the digitizer toolbar in the "Select +vector map" combobox. This map is then opened for editing and added to +the current layer tree in the *Layer Manager*. This "Select vector map" +combobox in the digitizer toolbar also allows to easily switch between +vector maps to be edited. + +### USING A RASTER BACKGROUND MAP + +In order to digitize from a raster map, simply load the map into the +*Map Display* using the *Layer Manager*. Then start digitizing, see +below for details. + +### USING A VECTOR BACKGROUND MAP + +The vector digitizer allows you to select a "background" vector map. +Loading it within the digitizer is different from simply loading it via +*Layer Manager* since direct interaction with single vector features +then becomes possible. +Vector features may be copied from the background map by "Copy features +from (background) vector map" tool from the "Additional tools" of the +digitizer toolbar. Newly digitized vector features are snapped in the +given threshold to the features from the background map. + +### DIGITIZER TOOLBAR + + + +![icon](icons/point-create.png)  *Digitize new point* +Add new point to vector map and optionally define its attributes +(Ctrl+P). + +![icon](icons/line-create.png)  *Digitize new line* +Add new line to vector map and optionally define its attributes +(Ctrl+L). + +![icon](icons/boundary-create.png)  *Digitize new boundary* +Add new boundary to vector map and optionally define its attributes +(Ctrl+B). + +![icon](icons/centroid-create.png)  *Digitize new centroid* +Add new centroid to vector map and optionally define its attributes +(Ctrl+C). + +![icon](icons/polygon-create.png)  *Digitize new area* +Add new area (closed boundary and one centroid inside) to vector map and +optionally define its attributes (Ctrl+A). + +![icon](icons/vertex-move.png)  *Move vertex* +Move selected vertex of linear feature. Thus shape of linear feature is +changed (Ctrl+G). + +![icon](icons/vertex-create.png)  *Add vertex* +Add new vertex to selected linear feature (shape not changed) (Ctrl+V). + +![icon](icons/vertex-delete.png)  *Remove vertex* +Remove selected vertex from linear feature (Ctrl+X). Thus shape of +selected feature can be changed. + +![icon](icons/line-edit.png)  *Edit line/boundary* +Edit selected linear feature, add new segments or remove existing +segments of linear feature (Ctrl+E). + +![icon](icons/line-move.png)  *Move feature(s)* +Move selected vector features (Ctrl+M.) Selection can be done by mouse +or by query. + +![icon](icons/line-delete.png)  *Delete feature(s)* +Delete selected vector features (point, line, centroid, or boundary) +(Ctrl+D). Selection can be done by mouse or by query. + +![icon](icons/polygon-delete.png)  *Delete areas(s)* +Delete selected vector areas (Ctrl+F). Selection can be done by mouse or +by query. + +![icon](icons/cats-display.png)  *Display/update categories* +Display categories of selected vector feature (Ctrl+J). Category +settings can be modified, new layer/category pairs added or already +defined pairs removed. + +![icon](icons/attributes-display.png)  *Display/update attributes* +Display attributes of selected vector feature (based on its category +settings) (Ctrl+K). Attributes can be also modified. Same functionality +is accessible from Main toolbar "Query vector map (editable mode)". + +![icon](icons/tools.png)  *Additional tools* + +- *Break selected lines/boundaries at intersection* + Split given vector line or boundary into two lines on given position + (based on *[v.clean](v.clean.md)*, `tool=break`). +- *Connect two selected lines/boundaries* + Connect selected lines or boundaries, the first given line is + connected to the second one. The second line is broken if necessary on + each intersection. The lines are connected only if distance between + them is not greater than snapping threshold value. +- *Copy categories* + Copy category settings of selected vector feature to other vector + features. Layer/category pairs of source vector features are appended + to the target feature category settings. Existing layer/category pairs + are not removed from category settings of the target features. +- *Copy features from (background) vector map* + Make identical copy of selected vector features. If a background + vector map has been selected from the Layer Manager, copy features + from background vector map, not from the currently modified vector + map. +- *Copy attributes* + Duplicate attributes settings of selected vector feature to other + vector features. New category(ies) is appended to the target feature + category settings and attributes duplicated based on category settings + of source vector features. Existing layer/category pairs are not + removed from category settings of the target features. +- *Feature type conversion* + Change feature type of selected geometry features. Points are + converted to centroids, centroids to points, lines to boundaries and + boundaries to lines. +- *Flip selected lines/boundaries* + Flip direction of selected linear features (lines or boundaries). +- *Merge selected lines/boundaries* + Merge (at least two) selected vector lines or boundaries. The geometry + of the merged vector lines can be changed. If the second line from two + selected lines is in opposite direction to the first, it will be + flipped. See also module *[v.build.polylines](v.build.polylines.md)*. +- *Snap selected lines/boundaries (only to nodes)* + Snap vector features in given threshold. See also module + *[v.clean](v.clean.md)*. Note that this tool supports only snapping to + nodes. Snapping to vector features from background vector map is not + currently supported. +- *Split line/boundary* + Split selected line or boundary on given position. +- *Query tool* + Select vector features by defining a threshold for min/max length + value (linear features or dangles). +- *Z-bulk labeling of 3D lines* + Assign z coordinate values to 3D vector lines in bounding box. This is + useful for labeling contour lines. + +![icon](icons/undo.png)  *Undo* +Undo previous operations (Ctrl+Z). + +![icon](icons/redo.png)  *Redo* +Redo previous operations (Ctrl+Y). + +![icon](icons/settings.png)  *Settings* +Digitizer settings (Ctrl+T). + +![icon](icons/help.png)  *Show help* +Show help page for the Digitizer (Ctrl+H). + +![icon](icons/quit.png)  *Quit digitizing tool* +Changes in vector map can be optionally discarded when digitizing +session is quited (Ctrl+Q). + +## NOTES + +**Mouse button functions:** + +*Left* - select or deselect features + +*Control+Left* - cancel action or undo vertex when digitizing lines + +*Right* - confirm action + +*Dead (deleted)* features are only marked as 'dead' in the geometry file +but remain there and occupy space. Any vector module used afterwards on +this vector map which really reads and writes vector geometry (so not +*[g.copy](g.copy.md)*) will write only features which are 'alive'. + +*Added or modified* vector features are *snapped* to existing vector +features (Settings→General→Snapping). To disable snapping set the +snapping threshold to '0'. + +If the digitizer crashes for some reason, the changes are automatically +saved. Broken topology can be repaired by running +*[v.build](v.build.md)*. + +GRASS GIS uses a topological vector format, meaning that a common +boundary of two polygons is only stored once. When digitizing polygons +it is thus important to be able to only draw each boundary once. When +drawing a polygon adjacent to an existing polygon, one has to first +split the existing boundary at the points where the new boundary will be +attached. Snapping should be set to ensure that the new boundaries are +automatically attached to the chosen points. + +## REFERENCES + +- [GRASS Vedit + Library](https://grass.osgeo.org/programming8/veditlib.html) +- [Vector Database + Management](https://grasswiki.osgeo.org/wiki/Vector_Database_Management) + (Wiki page) + +## SEE ALSO + +*[wxGUI](wxGUI.md), [wxGUI components](wxGUI.components.md)* + +*[v.edit](v.edit.md), [v.category](v.category.md), +[v.build](v.build.md), [g.gui.rdigit](g.gui.rdigit.md), +[wxGUI.rdigit](wxGUI.rdigit.md)* + +See also the [WxGUI Vector Digitizer Wiki +page](https://grasswiki.osgeo.org/wiki/WxGUI_Vector_Digitizer) including +[video +tutorials](https://grasswiki.osgeo.org/wiki/WxGUI_Vector_Digitizer#Vector_tutorials). + +## AUTHOR + +Martin Landa, FBK-irst (2007-2008), Trento, Italy, and Czech Technical +University in Prague, Czech Republic diff --git a/imagery/i.albedo/i.albedo.md b/imagery/i.albedo/i.albedo.md new file mode 100644 index 00000000000..6105b8480f9 --- /dev/null +++ b/imagery/i.albedo/i.albedo.md @@ -0,0 +1,58 @@ +## DESCRIPTION + +*i.albedo* calculates the albedo, that is the Shortwave surface +reflectance in the range of 0.3-3 micro-meters. It takes as input +individual bands of surface reflectance originating from MODIS, AVHRR, +Landsat or Aster satellite sensors and calculates the albedo for those. +This is a precursor to *r.sun* and any energy-balance processing. + +## NOTES + +It uses for Landsat 8 the weighted average reflectance (temporary +solution until an algorithm is found). + +It assumes MODIS product surface reflectance in \[0;10000\]. + +## EXAMPLE + +The following example creates the raster map "albedo_lsat7_1987" from +the LANDSAT-TM5 bands in the North Carolina dataset: + +```bash +g.region raster=lsat5_1987_10 -p +i.albedo -l input=lsat5_1987_10,lsat5_1987_20,lsat5_1987_30,lsat5_1987_40,lsat5_1987_50,lsat5_1987_70 output=albedo_lsat7_1987 +``` + +![i.albedo LANDSAT-TM5 1987 example](i_albedo_landsat5.png) +*Figure: Resulting albedo map from LANDSAT 5* + +The following example creates the raster map "albedo_lsat7_2000" from +the LANDSAT-TM7 bands in the North Carolina dataset: + +```bash +g.region raster=lsat7_2000_10 -p +i.albedo -l input=lsat7_2000_10,lsat7_2000_20,lsat7_2000_30,lsat7_2000_40,lsat7_2000_50,lsat7_2000_70 output=albedo_lsat7_2000 +``` + +![i.albedo LANDSAT-TM7 2000 example](i_albedo_landsat7.png) +*Figure: Resulting albedo map from LANDSAT 7* + +## TODO + +Maybe change input requirement of MODIS to \[0.0-1.0\]? + +## REFERENCES + +For a 2 band determination of the Aster BB Albedo see the following: + +Salleh and Chan, 2014. Land Surface Albedo Determination: Remote Sensing +and Statistical Validation. in proceedings of FIG 2014 +([PDF](https://www.fig.net/resources/proceedings/fig_proceedings/fig2014/papers/ts05g/TS05G_salleh_chan_6910.pdf)) + +## SEE ALSO + +*[r.sun](r.sun.md), [i.vi](i.vi.md)* + +## AUTHOR + +Yann Chemin diff --git a/imagery/i.aster.toar/i.aster.toar.md b/imagery/i.aster.toar/i.aster.toar.md new file mode 100644 index 00000000000..8118c9cf0f4 --- /dev/null +++ b/imagery/i.aster.toar/i.aster.toar.md @@ -0,0 +1,40 @@ +## DESCRIPTION + +*i.aster.toar* calculates the Top Of Atmosphere (TOA) reflectance for +Terra-ASTER L1B in the visible, NIR and SWIR bands (9+1 bands) and +brightness temperature for the TIR bands (5 bands), all from L1B DN +values. It is useful to apply after import of original ASTER imagery +that is generally in standard DN values range. + +The order of input bands is + +- VNIR: 1,2,3N,3B +- SWIR: 4,5,6,7,8,9 +- TIR: 10,11,12,13,14 + +in one comma-separated list. + +## NOTES + +Internally, a gain code is defined to modify gains according to spectral +bands following the GeoSystems GmbH ATCOR Ver. 2.0 Calibration Files. +The function is defined in gain_aster.c file. + +```bash +/*Gain Code*/ + /*0 - High (Not Applicable for band 10-14: TIR)*/ + /*1 - Normal*/ + /*2 - Low 1(Not Applicable for band 10-14: TIR)*/ + /*3 - Low 2(Not Applicable for Band 1-3N/B and 10-14)*/ +``` + +## SEE ALSO + +*[i.landsat.toar](i.landsat.toar.md), [r.in.aster](r.in.aster.md)* + +ASTER sensor data download: [ASTER: Advanced Spaceborne Thermal Emission +and Reflection Radiometer](https://asterweb.jpl.nasa.gov/) + +## AUTHOR + +Yann Chemin, CSU, Australia diff --git a/imagery/i.atcorr/i.atcorr.md b/imagery/i.atcorr/i.atcorr.md new file mode 100644 index 00000000000..8c1c20d1999 --- /dev/null +++ b/imagery/i.atcorr/i.atcorr.md @@ -0,0 +1,1112 @@ +## DESCRIPTION + +**i.atcorr** performs atmospheric correction on the input raster map +using the 6S algorithm (*Second Simulation of Satellite Signal in the +Solar Spectrum*). A detailed algorithm description is available at the +[Land Surface Reflectance Science Computing Facility +website](https://salsa.umd.edu/). + +*Important: Current region settings are ignored!* The region is adjusted +to cover the input raster map before the atmospheric correction is +performed. The previous settings are restored afterwards. + +If the **-r** flag is used, the input raster map is treated as +*reflectance*. Otherwise, the input raster map is treated as *radiance* +values and it is converted to reflectance at the *i.atcorr* runtime. The +output data are always reflectance. + +The satellite overpass time has to be specified in Greenwich Mean Time +(GMT). + +An example of the 6S parameters could be: + +```bash +8 - geometrical conditions=Landsat ETM+ +2 19 13.00 -47.410 -20.234 - month day hh.ddd longitude latitude ("hh.ddd" is in decimal hours GMT) +1 - atmospheric model=tropical +1 - aerosols model=continental +15 - visibility [km] (aerosol model concentration) +-0.600 - mean target elevation above sea level [km] (here 600 m asl) +-1000 - sensor height (here, sensor on board a satellite) +64 - 4th band of ETM+ Landsat 7 +``` + +If the position is not available in longitude-latitude (WGS84), the +*[m.proj](m.proj.md)* conversion module can be used to reproject from a +different reference system. + +## 6S CODE PARAMETER CHOICES + +### A. Geometrical conditions + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeDescriptionDetails
1meteosat observationenter month,day,decimal hour (universal time-hh.ddd)
+                      n. of column,n. of line. (full scale +5000*2500) 
2goes east observationenter month,day,decimal hour (universal time-hh.ddd)
+                      n. of column,n. of line. (full scale +17000*12000)c
3goes west observationenter month,day,decimal hour (universal time-hh.ddd)
+                      n. of column,n. of line. (full scale +17000*12000)
4avhrr (PM noaa)enter month,day,decimal hour (universal time-hh.ddd)
+                      n. of column(1-2048),xlonan,hna
+                      give long.(xlonan) and overpass hour (hna) +at
+                      the ascendant node at equator
5avhrr (AM noaa)enter month,day,decimal hour (universal time-hh.ddd)
+                      n. of column(1-2048),xlonan,hna
+                      give long.(xlonan) and overpass hour (hna) +at
+                      the ascendant node at equator
6hrv (spot)enter month,day,hh.ddd,long.,lat. *
7tm (landsat)enter month,day,hh.ddd,long.,lat. *
8etm+ (landsat7)enter month,day,hh.ddd,long.,lat. *
9liss (IRS 1C)enter month,day,hh.ddd,long.,lat. *
10asterenter month,day,hh.ddd,long.,lat. *
11avnirenter month,day,hh.ddd,long.,lat. *
12ikonosenter month,day,hh.ddd,long.,lat. *
13RapidEyeenter month,day,hh.ddd,long.,lat. *
14VGT1 (SPOT4)enter month,day,hh.ddd,long.,lat. *
15VGT2 (SPOT5)enter month,day,hh.ddd,long.,lat. *
16WorldView 2enter month,day,hh.ddd,long.,lat. *
17QuickBirdenter month,day,hh.ddd,long.,lat. *
18LandSat 8enter month,day,hh.ddd,long.,lat. *
19Geoeye 1enter month,day,hh.ddd,long.,lat. *
20Spot6enter month,day,hh.ddd,long.,lat. *
21Spot7enter month,day,hh.ddd,long.,lat. *
22Pleiades1Aenter month,day,hh.ddd,long.,lat. *
23Pleiades1Benter month,day,hh.ddd,long.,lat. *
24Worldview3enter month,day,hh.ddd,long.,lat. *
25Sentinel-2Aenter month,day,hh.ddd,long.,lat. *
26Sentinel-2Benter month,day,hh.ddd,long.,lat. *
27PlanetScope 0c 0denter month,day,hh.ddd,long.,lat. *
28PlanetScope 0eenter month,day,hh.ddd,long.,lat. *
29PlanetScope 0f 10enter month,day,hh.ddd,long.,lat. *
30Worldview4enter month,day,hh.ddd,long.,lat. *
31AVIRISenter month,day,hh.ddd,long.,lat. *
32Hyperion VNIRenter month,day,hh.ddd,long.,lat. *
33Hyperion SWIRenter month,day,hh.ddd,long.,lat. *
+ +> *NOTE*: for HRV, TM, ETM+, LISS and ASTER experiments, longitude and +> latitude are the coordinates of the scene center. Latitude must be \> +> 0 for northern hemisphere and \< 0 for southern. Longitude must be \> +> 0 for eastern hemisphere and \< 0 for western. + +### B. Atmospheric model + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeMeaning
0no gaseous absorption
1tropical
2midlatitude summer
3midlatitude winter
4subarctic summer
5subarctic winter
6us standard 62
7Define your own atmospheric model as a set of the following 5 +parameters per each measurement:
+
+altitude [km]
+pressure [mb]
+temperature [k]
+h2o density [g/m3]
+o3 density [g/m3]
+
+For example: there is one radiosonde measurement for each altitude of +0-25km at a step of 1km, one measurement for each altitude of 25-50km at +a step of 5km, and two single measurements for altitudes 70km and 100km. +This makes 34 measurements. In that case, there are 34*5 values to +input.
8Define your own atmospheric model providing values of the water +vapor and ozone content:
+
+uw [g/cm2]
+uo3 [cm-atm]
+
+The profile is taken from us62.
+ +### C. Aerosols model + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeMeaningDetails
0no aerosols 
1continental model 
2maritime model 
3urban model 
4shettle model for background desert aerosol 
5biomass burning 
6stratospheric model 
7define your own modelEnter the volumic percentage of each component:
+
+c(1) = volumic % of dust-like
+c(2) = volumic % of water-soluble
+c(3) = volumic % of oceanic
+c(4) = volumic % of soot
+
+All values should be between 0 and 1.
8define your own modelSize distribution function: Multimodal Log Normal (up to 4 +modes).
9define your own modelSize distribution function: Modified gamma.
10define your own modelSize distribution function: Junge Power-Law.
11define your own modelSun-photometer measurements, 50 values max, entered as:
+
+r and d V / d (logr)
+
+where r is the radius [micron], V is the volume, d V / d (logr) +[cm3/cm2/micron].
+
+Followed by:
+
+nr and ni for each wavelength
+
+where nr and ni are respectively the real and imaginary part of the +refractive index.
+ +### D. Aerosol concentration model (visibility) + +If you have an estimate of the meteorological parameter visibility v, +enter directly the value of v \[km\] (the aerosol optical depth (AOD) +will be computed from a standard aerosol profile). + +If you have an estimate of aerosol optical depth, enter 0 for the +visibility and in a following line enter the aerosol optical depth at +550nm (iaer means 'i' for input and 'aer' for aerosol), for example: + +```bash +0 - visibility +0.112 - aerosol optical depth at 550 nm +``` + +NOTE: if iaer is 0, enter -1 for visibility. + +NOTE: if a visibility map is provided, these parameters are ignored. + +### E. Target altitude (xps), sensor platform (xpp) + +Target altitude (xps, in negative \[km\]): + +> xps \>= 0 means the target is at the sea level. +> otherwise xps expresses the altitude of the target (e.g., mean +> elevation) in \[km\], given as negative value + +Sensor platform (xpp, in negative \[km\] or -1000): + +> +> xpp = -1000 means that the sensor is on board a satellite. +> xpp = 0 means that the sensor is at the ground level. +> -100 \< xpp \< 0 defines the altitude of the sensor expressed in +> \[km\]; this altitude is given **relative to the target** altitude as +> negative value. + +For aircraft simulations only (xpp is neither equal to 0 nor equal to +-1000): + +> puw (water vapor content between the aircraft and the surface) +> po3 (ozone content between the aircraft and the surface) +> taerp (the aerosol optical thickness at 550nm between the aircraft and +> the surface) +> +> If these data are not available, enter negative values for all of +> them. puw,po3 will then be interpolated from the us62 standard profile +> according to the values at the ground level; taerp will be computed +> according to a 2 km exponential profile for aerosol. + +### F. Sensor band + +There are two possibilities: either define your own spectral conditions +(codes -2, -1, 0, or 1) or choose a code indicating the band of one of +the pre-defined satellites. + +Define your own spectral conditions: Note that "wlinf" and "wlsup" refer +to the limits of the wavelength range defined by the user for a given +simulation. Specifically: + +- wlinf: This represents the lower wavelength limit (or minimum + wavelength) of the spectral band for which the simulation is being + performed. +- wlsup: This represents the upper wavelength limit (or maximum + wavelength) of the spectral band for the simulation. + + ++++ + + + + + + + + + + + + + + + + + + + + + + +
CodeMeaning
-2Enter wlinf, wlsup.
+The filter function will be equal to 1 over the whole band (as iwave=0) +but step by step output will be printed.
-1Enter wl (monochr. cond, gaseous absorption is included).
0Enter wlinf, wlsup.
+The filter function will be equal to 1 over the whole band.
1Enter wlinf, wlsup and user's filter function s (lambda) by step of +0.0025 micrometer.
+ +Pre-defined satellite bands: + +| | | +|----------|-----------------------------------------------------| +| **Code** | **Band name (peak response)** | +| 2 | **meteosat** vis band (0.350-1.110) | +| 3 | **goes east** band vis (0.490-0.900) | +| 4 | **goes west** band vis (0.490-0.900) | +| 5 | **avhrr** (noaa6) band 1 (0.550-0.750) | +| 6 | avhrr (noaa6) band 2 (0.690-1.120) | +| 7 | avhrr (noaa7) band 1 (0.500-0.800) | +| 8 | avhrr (noaa7) band 2 (0.640-1.170) | +| 9 | avhrr (noaa8) band 1 (0.540-1.010) | +| 10 | avhrr (noaa8) band 2 (0.680-1.120) | +| 11 | avhrr (noaa9) band 1 (0.530-0.810) | +| 12 | avhrr (noaa9) band 1 (0.680-1.170) | +| 13 | avhrr (noaa10) band 1 (0.530-0.780) | +| 14 | avhrr (noaa10) band 2 (0.600-1.190) | +| 15 | avhrr (noaa11) band 1 (0.540-0.820) | +| 16 | avhrr (noaa11) band 2 (0.600-1.120) | +| 17 | **hrv1** (spot1) band 1 (0.470-0.650) | +| 18 | hrv1 (spot1) band 2 (0.600-0.720) | +| 19 | hrv1 (spot1) band 3 (0.730-0.930) | +| 20 | hrv1 (spot1) band pan (0.470-0.790) | +| 21 | hrv2 (spot1) band 1 (0.470-0.650) | +| 22 | hrv2 (spot1) band 2 (0.590-0.730) | +| 23 | hrv2 (spot1) band 3 (0.740-0.940) | +| 24 | hrv2 (spot1) band pan (0.470-0.790) | +| 25 | **tm** (landsat5) band 1 (0.430-0.560) | +| 26 | tm (landsat5) band 2 (0.500-0.650) | +| 27 | tm (landsat5) band 3 (0.580-0.740) | +| 28 | tm (landsat5) band 4 (0.730-0.950) | +| 29 | tm (landsat5) band 5 (1.5025-1.890) | +| 30 | tm (landsat5) band 7 (1.950-2.410) | +| 31 | **mss** (landsat5) band 1 (0.475-0.640) | +| 32 | mss (landsat5) band 2 (0.580-0.750) | +| 33 | mss (landsat5) band 3 (0.655-0.855) | +| 34 | mss (landsat5) band 4 (0.785-1.100) | +| 35 | **MAS** (ER2) band 1 (0.5025-0.5875) | +| 36 | MAS (ER2) band 2 (0.6075-0.7000) | +| 37 | MAS (ER2) band 3 (0.8300-0.9125) | +| 38 | MAS (ER2) band 4 (0.9000-0.9975) | +| 39 | MAS (ER2) band 5 (1.8200-1.9575) | +| 40 | MAS (ER2) band 6 (2.0950-2.1925) | +| 41 | MAS (ER2) band 7 (3.5800-3.8700) | +| 42 | **MODIS** band 1 (0.6100-0.6850) | +| 43 | MODIS band 2 (0.8200-0.9025) | +| 44 | MODIS band 3 (0.4500-0.4825) | +| 45 | MODIS band 4 (0.5400-0.5700) | +| 46 | MODIS band 5 (1.2150-1.2700) | +| 47 | MODIS band 6 (1.6000-1.6650) | +| 48 | MODIS band 7 (2.0575-2.1825) | +| 49 | **avhrr** (noaa12) band 1 (0.500-1.000) | +| 50 | avhrr (noaa12) band 2 (0.650-1.120) | +| 51 | avhrr (noaa14) band 1 (0.500-1.110) | +| 52 | avhrr (noaa14) band 2 (0.680-1.100) | +| 53 | **POLDER** band 1 (0.4125-0.4775) | +| 54 | POLDER band 2 (non polar) (0.4100-0.5225) | +| 55 | POLDER band 3 (non polar) (0.5325-0.5950) | +| 56 | POLDER band 4 P1 (0.6300-0.7025) | +| 57 | POLDER band 5 (non polar) (0.7450-0.7800) | +| 58 | POLDER band 6 (non polar) (0.7000-0.8300) | +| 59 | POLDER band 7 P1 (0.8100-0.9200) | +| 60 | POLDER band 8 (non polar) (0.8650-0.9400) | +| 61 | **etm+ (landsat7)** band 1 blue (435nm - 517nm) | +| 62 | etm+ (landsat7) band 2 green (508nm - 617nm) | +| 63 | etm+ (landsat7) band 3 red (625nm - 702nm) | +| 64 | etm+ (landsat7) band 4 NIR (753nm - 910nm) | +| 65 | etm+ (landsat7) band 5 SWIR (1520nm - 1785nm) | +| 66 | etm+ (landsat7) band 7 SWIR (2028nm - 2375nm) | +| 67 | etm+ (landsat7) band 8 PAN (505nm - 917nm) | +| 68 | **liss** (IRC 1C) band 2 (0.502-0.620) | +| 69 | liss (IRC 1C) band 3 (0.612-0.700) | +| 70 | liss (IRC 1C) band 4 (0.752-0.880) | +| 71 | liss (IRC 1C) band 5 (1.452-1.760) | +| 72 | **aster** band 1 (0.480-0.645) | +| 73 | aster band 2 (0.588-0.733) | +| 74 | aster band 3N (0.723-0.913) | +| 75 | aster band 4 (1.530-1.750) | +| 76 | aster band 5 (2.103-2.285) | +| 77 | aster band 6 (2.105-2.298) | +| 78 | aster band 7 (2.200-2.393) | +| 79 | aster band 8 (2.248-2.475) | +| 80 | aster band 9 (2.295-2.538) | +| 81 | **avnir** band 1 (408nm - 517nm) | +| 82 | avnir band 2 (503nm - 612nm) | +| 83 | avnir band 3 (583nm - 717nm) | +| 84 | avnir band 4 (735nm - 922nm) | +| 85 | **Ikonos** Green band (408nm - 642nm) | +| 86 | Ikonos Red band (448nm - 715nm) | +| 87 | Ikonos NIR band (575nm - 787nm) | +| 88 | **RapidEye** Blue band (440nm - 512nm) | +| 89 | RapidEye Green band (515nm - 592nm) | +| 90 | RapidEye Red band (628nm - 687nm) | +| 91 | RapidEye Red edge band (685nm - 735nm) | +| 92 | RapidEye NIR band (750nm - 860nm) | +| 93 | **VGT1 (SPOT4)** band 0 (420nm - 497nm) | +| 94 | VGT1 (SPOT4) band 2 (603nm - 747nm) | +| 95 | VGT1 (SPOT4) band 3 (740nm - 942nm) | +| 96 | VGT1 (SPOT4) MIR band (1540nm - 1777nm) | +| 97 | **VGT2 (SPOT5)** band 0 (423nm - 492nm) | +| 98 | VGT2 (SPOT5) band 2 (600nm - 737nm) | +| 99 | VGT2 (SPOT5) band 3 (745nm - 945nm) | +| 100 | VGT2 (SPOT5) MIR band (1523nm - 1757nm) | +| 101 | **WorldView2** Panchromatic band (448nm - 812nm) | +| 102 | WorldView2 Coastal Blue band (395nm - 457nm) | +| 103 | WorldView2 Blue band (440nm - 517nm) | +| 104 | WorldView2 Green band (503nm - 587nm) | +| 105 | WorldView2 Yellow band (583nm - 632nm) | +| 106 | WorldView2 Red band (623nm - 695nm) | +| 107 | WorldView2 Red edge band (698nm - 750nm) | +| 108 | WorldView2 NIR1 band (760nm - 905nm) | +| 109 | WorldView2 NIR2 band (853nm - 1047nm) | +| 110 | **QuickBird** Panchromatic band (385nm - 1060nm) | +| 111 | QuickBird Blue band (420nm - 585nm) | +| 112 | QuickBird Green band (448nm - 682nm) | +| 113 | QuickBird Red band (560nm - 747nm) | +| 114 | QuickBird NIR1 band (650nm - 935nm) | +| 115 | **Landsat 8** Coastal aerosol band (433nm - 455nm) | +| 116 | Landsat 8 Blue band (448nm - 515nm) | +| 117 | Landsat 8 Green band (525nm - 595nm) | +| 118 | Landsat 8 Red band (633nm - 677nm) | +| 119 | Landsat 8 Panchromatic band (498nm - 682nm) | +| 120 | Landsat 8 NIR band (845nm - 885nm) | +| 121 | Landsat 8 Cirrus band (1355nm - 1390nm) | +| 122 | Landsat 8 SWIR1 band (1540nm - 1672nm) | +| 123 | Landsat 8 SWIR2 band (2073nm - 2322nm) | +| 124 | **GeoEye 1** Panchromatic band (448nm - 812nm) | +| 125 | GeoEye 1 Blue band (443nm - 525nm) | +| 126 | GeoEye 1 Green band (503nm - 587nm) | +| 127 | GeoEye 1 Red band (653nm - 697nm) | +| 128 | GeoEye 1 NIR band (770nm - 932nm) | +| 129 | **Spot6** Blue band (440nm - 532nm) | +| 130 | Spot6 Green band (515nm - 600nm) | +| 131 | Spot6 Red band (610nm - 710nm) | +| 132 | Spot6 NIR band (738nm - 897nm) | +| 133 | Spot6 Pan band (438nm - 760nm) | +| 134 | **Spot7** Blue band (445nm - 532nm) | +| 135 | Spot7 Green band (525nm - 607nm) | +| 136 | Spot7 Red band (610nm - 727nm) | +| 137 | Spot7 NIR band (745nm - 902nm) | +| 138 | Spot7 Pan band (443nm - 760nm) | +| 139 | **Pleiades1A** Blue band (433nm - 560nm) | +| 140 | Pleiades1A Green band (500nm - 617nm) | +| 141 | Pleiades1A Red band (590nm - 722nm) | +| 142 | Pleiades1A NIR band (740nm - 945nm) | +| 143 | Pleiades1A Pan band (460nm - 845nm) | +| 144 | **Pleiades1B** Blue band 438nm - 560nm) | +| 145 | Pleiades1B Green band (498nm - 615nm) | +| 146 | Pleiades1B Red band (608nm - 727nm) | +| 147 | Pleiades1B NIR band (750nm - 945nm) | +| 148 | Pleiades1B Pan band (460nm - 845nm) | +| 149 | **Worldview3** Pan band (445nm - 812nm) | +| 150 | Worldview3 Coastal blue band (395nm - 455nm) | +| 151 | Worldview3 Blue band (443nm - 517nm) | +| 152 | Worldview3 Green band (508nm - 587nm) | +| 153 | Worldview3 Yellow band (580nm - 630nm) | +| 154 | Worldview3 Red band (625nm - 697nm) | +| 155 | Worldview3 Red edge band (698nm - 752nm) | +| 156 | Worldview3 NIR1 band (760nm - 902nm) | +| 157 | Worldview3 NIR2 band (855nm - 1042nm) | +| 158 | Worldview3 SWIR1 band (1178nm - 1242nm) | +| 159 | Worldview3 SWIR2 band (1545nm - 1600nm) | +| 160 | Worldview3 SWIR3 band (1633nm - 1687nm) | +| 161 | Worldview3 SWIR4 band (1698nm - 1762nm) | +| 162 | Worldview3 SWIR5 band (2133nm - 2195nm) | +| 163 | Worldview3 SWIR6 band (2170nm - 2235nm) | +| 164 | Worldview3 SWIR7 band (2225nm - 2295nm) | +| 165 | Worldview3 SWIR8 band (2283nm - 2377nm) | +| 166 | **Sentinel2A** Coastal blue band B1 (430nm - 455nm) | +| 167 | Sentinel2A Blue band B2 (440nm - 530nm) | +| 168 | Sentinel2A Green band B3 (540nm - 580nm) | +| 169 | Sentinel2A Red band B4 (648nm - 682nm) | +| 170 | Sentinel2A Red edge band B5 (695nm - 712nm) | +| 171 | Sentinel2A Red edge band B6 (733nm - 747nm) | +| 172 | Sentinel2A Red edge band B7 (770nm - 795nm) | +| 173 | Sentinel2A NIR band B8 (775nm - 905nm) | +| 174 | Sentinel2A Red edge band B8A (850nm - 880nm) | +| 175 | Sentinel2A Water vapour band B9 (933nm - 957nm) | +| 176 | Sentinel2A SWIR Cirrus band B10 (1355nm - 1392nm) | +| 177 | Sentinel2A SWIR band B11 (1558nm - 1667nm) | +| 178 | Sentinel2A SWIR band B12 (2088nm - 2315nm) | +| 179 | **Sentinel2B** Coastal blue band B1 (430nm - 455nm) | +| 180 | Sentinel2B Blue band B2 (440nm - 530nm) | +| 181 | Sentinel2B Green band B3 (538nm - 580nm) | +| 182 | Sentinel2B Red band B4 (648nm - 682nm) | +| 183 | Sentinel2B Red edge band B5 (695nm - 712nm) | +| 184 | Sentinel2B Red edge band B6 (730nm - 747nm) | +| 185 | Sentinel2B Red edge band B7 (768nm - 792nm) | +| 186 | Sentinel2B NIR band B8 (778nm - 905nm) | +| 187 | Sentinel2B Red edge band B8A (850nm - 877nm) | +| 188 | Sentinel2B Water vapour band B9 (930nm - 955nm) | +| 189 | Sentinel2B SWIR Cirrus band B10 (1358nm - 1397nm) | +| 190 | Sentinel2B SWIR band B11 (1555nm - 1667nm) | +| 191 | Sentinel2B SWIR band B12 (2075nm - 2300nm) | +| 192 | **PlanetScope 0c 0d** Blue band B1 (440nm - 570nm) | +| 193 | PlanetScope 0c 0d Green band B2 (450nm - 690nm) | +| 194 | PlanetScope 0c 0d Red band B3 (460nm - 700nm) | +| 195 | PlanetScope 0c 0d NIR band B4 (770nm - 880nm) | +| 196 | **PlanetScope 0e** Blue band B1 (430nm - 700nm) | +| 197 | PlanetScope 0e Green band B2 (450nm - 700nm) | +| 198 | PlanetScope 0e Red band B3 (460nm - 700nm) | +| 199 | PlanetScope 0e NIR band B4 (760nm - 880nm) | +| 200 | **PlanetScope 0f 10** Blue band B1 (450nm - 680nm) | +| 201 | PlanetScope 0f 10 Green band B2 (450nm - 680nm) | +| 202 | PlanetScope 0f 10 Red band B3 (450nm - 680nm) | +| 203 | PlanetScope 0f 10 NIR band B4 (760nm - 870nm) | +| 204 | **Worldview4** Pan band (424nm - 842nm) | +| 205 | Worldview4 Blue band (416nm - 567nm) | +| 206 | Worldview4 Green band (488nm - 626nm) | +| 207 | Worldview4 Red band (639nm - 711nm) | +| 208 | Worldview4 NIR1 band (732nm - 962nm) | +| 209 | **AVIRIS** b1 band (365nm) | +| 210 | AVIRIS b2 band (375nm) | +| . | AVIRIS b. band (+10nm) | +| 431 | AVIRIS b223 band (2486nm) | +| 432 | AVIRIS b224 band (2496nm) | +| 433 | **Hyperion** VNIR b8 band (427nm) | +| 434 | Hyperion VNIR b9 band (437.16326nm) | +| . | Hyperion VNIR b. band (+10.16326nm) | +| 480 | Hyperion VNIR b56 band (914.83648nm) | +| 481 | Hyperion VNIR b57 band (924.99974nm) | +| 482 | Hyperion SWIR b77 band (912nm) | +| 483 | Hyperion SWIR b78 band (922.0884nm) | +| . | Hyperion SWIR b. band (+10.0884nm) | +| 627 | Hyperion SWIR b223 band (2384.9064nm) | +| 628 | Hyperion SWIR b224 band (2394.9948nm) | + +## EXAMPLES + +### Atmospheric correction of a Sentinel-2 band + +This example illustrates how to perform atmospheric correction of a +Sentinel-2 scene in the North Carolina project. + +Let's assume that the Sentinel-2 L1C scene +*S2A_OPER_PRD_MSIL1C_PDMC_20161029T092602_R054_V20161028T155402_20161028T155402* +was downloaded and imported with region cropping (see +[r.import](r.import.md)) into the *PERMANENT* mapset of the North +Carolina project. The computational region was set to the extent of the +*elevation* map in the North Carolina dataset. Now, we have 13 +individual bands (*B01-B12*) that we want to apply the atmospheric +correction to. The following steps are applied to each band separately. + +**Create the parameters file for i.atcorr** + +In the first step we create a file containing the 6S parameters for a +particular scene and band. To create a 6S file, we need to obtain the +following information: + +- geometrical conditions, +- moth, day, decimal hours in GMT, decimal longitude and latitude of + measurement, +- atmospheric model, +- aerosol model, +- visibility or aerosol optical depth, +- mean target elevation above sea level, +- sensor height and, +- sensor band. + +1. *Geometrical conditions* + For Sentinel-2A, the geometrical conditions take the value `25` and + for Sentinel-2B, the geometrical conditions value is `26` (See table + A). Our scene comes from the Sentinel-2A mission (the file name + begins with S2A\_...). + +2. *Day, time, longitude and latitude of measurement* + + Day and time of the measurement are hidden in the filename (i.e., + the second datum in the file name with format `YYYYMMDDTHHMMSS`), + and are also noted in the metadata file, which is included in the + downloaded scene (file with .xml extension). Our sample scene was + taken on October 28th (20161028) at 15:54:02 (155402). Note that the + time has to be specified in decimal hours in Greenwich Mean Time + (GMT). Luckily, the time in the scene name is in GMT and we can + convert it to decimal hours as follows: 15 + 54/60 + 2/3600 = + 15.901. + + Longitude and latitude refer to the centre of the computational + region (which can be smaller than the scene), and must be in WGS84 + decimal coordinates. To obtain the coordinates of the centre, we can + run: + + ```bash + g.region -bg + ``` + + The longitude and latitude of the centre are stored in *ll_clon* and + *ll_clat*. In our case, `ll_clon=-78.691` and `ll_clat=35.749`. + +3. *Atmospheric model* + We can choose between various atmospheric models as defined at the + beginning of this manual. For North Carolina, we can choose + `2 - midlatitude summer`. + +4. *Aerosol model* + We can also choose between various aerosol models as defined at the + beginning of this manual. For North Carolina, we can choose + `1 - continental model`. + +5. *Visibility or Aerosol Optical Depth* + For Sentinel-2 scenes, the visibility is not measured, and therefore + we have to estimate the aerosol optical depth instead, e.g. from + [AERONET](https://aeronet.gsfc.nasa.gov). With a bit of luck, you + can find a station nearby your location, which measured the Aerosol + Optical Depth at 500 nm at the same time as the scene was taken. In + our case, on 28th October 2016, the *EPA-Res_Triangle_Pk* station + measured AOD = 0.07 (approximately). + +6. *Mean target elevation above sea level* + + Mean target elevation above sea level refers to the mean elevation + of the computational region. You can estimate it from the digital + elevation model, e.g. by running: + + ```bash + r.univar -g elevation + ``` + + The mean elevation is stored in *mean*. In our case, `mean=110`. In + the 6S file it will be displayed in \[-km\], i.e., `-0.110`. + +7. *Sensor height* + Since the sensor is on board a satellite, the sensor height will be + set to `-1000`. + +8. *Sensor band* + + The overview of satellite bands can be found in table F (see above). + For Sentinel-2A, the band numbers span from 166 to 178, and for + Sentinel-2B, from 179 to 191. + +Finally, here is what the 6S file would look like for Band 02 of our +scene. In order to use it in the *i.atcorr* module, we can save it in a +text file, for example `params_B02.txt`. + +```bash +25 +10 28 15.901 -78.691 35.749 +2 +1 +0 +0.07 +-0.110 +-1000 +167 +``` + +**Compute atmospheric correction** + +In the next step we run *i.atcorr* for the selected band *B02* of our +Sentinel 2 scene. We have to specify the following parameters: + +- **input** = raster band to be processed, +- **parameters** = path to 6S file created in the previous step (we + could also enter the values directly), +- **output** = name for the output corrected raster band, +- **range** = from 1 to the `QUANTIFICATION_VALUE` stored in the + metadata file. It is `10000` for both Sentinel-2A and Sentinel-2B. +- **rescale** = the output range of values for the corrected bands. This + is up to the user to choose, for example: 0-255, 0-1, 1-10000. + +If the data is available, the following parameters can be specified as +well: + +- **elevation** = raster of digital elevation model, +- **visibility** = raster of visibility model. + +Finally, this is how the command would look like to apply atmospheric +correction to band *B02*: + +```bash +i.atcorr input=B02 parameters=params_B02.txt output=B02.atcorr range=1,10000 rescale=0,255 elevation=elevation +``` + +To apply atmospheric correction to the remaining bands, only the last +line in the 6S parameters file (i.e., the sensor band) needs to be +changed. The other parameters will remain the same. + +
+ +[i.atcorr example](i_atcorr_B02_atcorr.png) +*Figure: Sentinel-2A Band 02 with applied atmospheric correction +(histogram equalization grayscale color scheme)* + +
+ +### Atmospheric correction of a Landsat-7 band + +This example is also based on the North Carolina sample dataset (GMT -5 +hours). First we set the computational region to the satellite map, e.g. +band 4: + +```bash +g.region raster=lsat7_2002_40 -p +``` + +It is important to verify the available metadata for the sun position +which has to be defined for the atmospheric correction. An option is to +check the satellite overpass time with sun position as reported in the +[metadata](ftp://ftp.glcf.umd.edu/glcf/Landsat/WRS2/p016/r035/p016r035_7x20020524.ETM-EarthSat-Orthorectified/p016r035_7x20020524.met) +file ([file +copy](https://grassbook.org/wp-content/uploads/ncexternal/landsat/2002/p016r035_7x20020524.met); +North Carolina sample dataset). In the case of the North Carolina sample +dataset, these values have been stored for each channel and can be +retrieved with: + +```bash +r.info lsat7_2002_40 +``` + +In this case, we have: SUN_AZIMUTH = 120.8810347, SUN_ELEVATION = +64.7730999. + +If the sun position metadata are unavailable, we can also calculate them +from the overpass time as follows (*[r.sunmask](r.sunmask.md)* uses +[SOLPOS](https://www.nrel.gov/grid/solar-resource/solpos.html)): + +```bash +r.sunmask -s elev=elevation out=dummy year=2002 month=5 day=24 hour=10 min=42 sec=7 timezone=-5 +# .. reports: sun azimuth: 121.342461, sun angle above horz.(refraction corrected): 65.396652 +``` + +If the overpass time is unknown, use the [NASA LaRC Satellite Overpass +Predictor](https://cloudsgate2.larc.nasa.gov/cgi-bin/predict/predict.cgi). + +#### Convert digital numbers (DN) to radiance at top-of-atmosphere (TOA) + +For Landsat and ASTER, the conversion can be conveniently done with +*[i.landsat.toar](i.landsat.toar.md)* or +*[i.aster.toar](i.aster.toar.md)*, respectively. + +In case of different satellites, the conversion of DN (digital number = +pixel values) to radiance at top-of-atmosphere (TOA) can also be done +manually, using e.g. the formula: + +```bash +# formula depends on satellite sensor, see respective metadata +Lλ = ((LMAXλ - LMINλ)/(QCALMAX-QCALMIN)) * (QCAL-QCALMIN) + LMINλ +``` + +where, + +- Lλ = Spectral Radiance at the sensor's aperture in Watt/(meter squared + \* ster \* µm), the apparent radiance as seen by the satellite sensor; +- QCAL = the quantized calibrated pixel value in DN; +- LMINλ = the spectral radiance that is scaled to QCALMIN in + watts/(meter squared \* ster \* µm); +- LMAXλ = the spectral radiance that is scaled to QCALMAX in + watts/(meter squared \* ster \* µm); +- QCALMIN = the minimum quantized calibrated pixel value (corresponding + to LMINλ) in DN; +- QCALMAX = the maximum quantized calibrated pixel value (corresponding + to LMAXλ) in DN=255. + +LMINλ and LMAXλ are the radiances related to the minimal and maximal DN +value, and they are reported in the metadata file of each image. High +gain or low gain is also reported in the metadata file of each satellite +image. For Landsat ETM+, the minimal DN value (QCALMIN) is 1 (see +[Landsat +handbook](https://landsat.gsfc.nasa.gov/wp-content/uploads/2016/08/Landsat7_Handbook.pdf), +chapter 11), and the maximal DN value (QCALMAX) is 255. QCAL is the DN +value for every separate pixel in the Landsat image. + +We extract the coefficients and apply them in order to obtain the +radiance map: + +```bash +CHAN=4 +r.info lsat7_2002_${CHAN}0 -h | tr '\n' ' ' | sed 's+ ++g' | tr ':' '\n' | grep "LMIN_BAND${CHAN}\|LMAX_BAND${CHAN}" +LMAX_BAND4=241.100,p016r035_7x20020524.met +LMIN_BAND4=-5.100,p016r035_7x20020524.met +QCALMAX_BAND4=255.0,p016r035_7x20020524.met +QCALMIN_BAND4=1.0,p016r035_7x20020524.met +``` + +Conversion to radiance (this calculation is done for band 4, for the +other bands, the numbers will need to be replaced with their related +values): + +```bash +r.mapcalc "lsat7_2002_40_rad = ((241.1 - (-5.1)) / (255.0 - 1.0)) * (lsat7_2002_40 - 1.0) + (-5.1)" +``` + +Again, the *r.mapcalc* calculation is only needed when working with +satellite data other than Landsat or ASTER. + +#### Create the parameters file for i.atcorr + +The underlying 6S model is parametrized through a control file, +indicated with the **parameters** option. This is a text file defining +geometrical and atmospherical conditions of the satellite overpass. Here +we create a control file `icnd_lsat4.txt` for band 4 (NIR), based on +metadata. For the overpass time, we need to define decimal hours: +10:42:07 NC local time = 10.70 decimal hours (decimal minutes: 42 \* 100 +/ 60) which is 15.70 GMT. + +```bash +8 - geometrical conditions=Landsat ETM+ +5 24 15.70 -78.691 35.749 - month day hh.ddd longitude latitude ("hh.ddd" is in GMT decimal hours) +2 - atmospheric model=midlatitude summer +1 - aerosols model=continental +50 - visibility [km] (aerosol model concentration) +-0.110 - mean target elevation above sea level [km] +-1000 - sensor on board a satellite +64 - 4th band of ETM+ Landsat 7 +``` + +Finally, run the atmospheric correction (-r for reflectance input map; +-a for date \> July 2000): + +```bash +i.atcorr -r -a lsat7_2002_40_rad elevation=elevation parameters=icnd_lsat4.txt output=lsat7_2002_40_atcorr +``` + +Note that the altitude value from 'icnd_lsat4.txt' file is read at the +beginning to compute the initial transform. Therefore, it is necessary +to provide a value that might be the mean value of the elevation model +(`r.univar elevation`). For the atmospheric correction per se, the +elevation values from the raster map are used. + +Note that the process is computationally intensive. Note also, that +*i.atcorr* reports solar elevation angle above horizon rather than solar +zenith angle. + +## REMAINING DOCUMENTATION ISSUES + +The influence and importance of the visibility value or map should be +explained, also how to obtain an estimate for either visibility or +aerosol optical depth at 550nm. + +## REFERENCES + +- Vermote, E.F., Tanre, D., Deuze, J.L., Herman, M., and Morcrette, + J.J., 1997, Second simulation of the satellite signal in the solar + spectrum, 6S: An overview., IEEE Trans. Geosc. and Remote Sens. + 35(3):675-686. +- 6S Manual: + [PDF1](http://www.rsgis.ait.ac.th/~honda/textbooks/advrs/6smanv2.0_P1.pdf), + [PDF2](http://www.rsgis.ait.ac.th/~honda/textbooks/advrs/6smanv2.0_P2.pdf), + and + [PDF3](http://www.rsgis.ait.ac.th/~honda/textbooks/advrs/6smanv2.0_P3.pdf) +- RapidEye sensors have been provided by [RapidEye AG, + Germany](https://www.planet.com/products/rapideye/) +- Barsi, J.A., Markham, B.L. and Pedelty, J.A., 2011, The operational + land imager: spectral response and spectral uniformity., Proc. SPIE + 8153, 81530G; doi:10.1117/12.895438 + +## SEE ALSO + +GRASS Wiki page about [Atmospheric +correction](https://grasswiki.osgeo.org/wiki/Atmospheric_correction) + +*[i.aster.toar](i.aster.toar.md), +[i.colors.enhance](i.colors.enhance.md), +[i.landsat.toar](i.landsat.toar.md), [r.info](r.info.md), +[r.mapcalc](r.mapcalc.md), [r.univar](r.univar.md)* + +## AUTHORS + +*Original version of the program for GRASS 5:* +Christo Zietsman, 13422863(at)sun.ac.za + +*Code clean-up and port to GRASS 6.3, 15.12.2006:* +Yann Chemin, ychemin(at)gmail.com + +*Documentation clean-up + IRS LISS sensor addition 5/2009:* +Markus Neteler, FEM, Italy + +*ASTER sensor addition 7/2009:* +Michael Perdue, Canada + +*AVNIR, IKONOS sensors addition 7/2010:* +Daniel Victoria, Anne Ghisla + +*RapidEye sensors addition 11/2010:* +Peter Löwe, Anne Ghisla + +*VGT1 and VGT2 sensors addition from [6SV-1.1 +sources](https://web.archive.org/web/20120207042414/http://6s.ltdri.org/), +addition 07/2011:* +Alfredo Alessandrini, Anne Ghisla + +*Added Landsat 8 from [NASA +sources](https://web.archive.org/web/20200616045331/https://landsat.gsfc.nasa.gov/preliminary-spectral-response-of-the-operational-land-imager-in-band-band-average-relative-spectral-response/), +addition 05/2014:* +Nikolaos Ves + +*Geoeye1 addition 7/2015:* +Marco Vizzari + +*Worldview3 addition 8/2016:* +Markus Neteler, mundialis.de, Germany + +*Sentinel-2A addition 12/2016:* +Markus Neteler, mundialis.de, Germany + +*Sentinel-2B addition 1/2018:* +Stefan Blumentrath, Zofie Cimburova, Norwegian Institute for Nature +Research, NINA, Oslo, Norway + +*Worldview4 addition 12/2018:* +Markus Neteler, mundialis.de, Germany + +*AVIRIS/Hyperion addition 11/2023:* +Yann Chemin, SOPHIA Engineering, FR diff --git a/imagery/i.biomass/i.biomass.md b/imagery/i.biomass/i.biomass.md new file mode 100644 index 00000000000..6aae759abbe --- /dev/null +++ b/imagery/i.biomass/i.biomass.md @@ -0,0 +1,44 @@ +## DESCRIPTION + +*i.biomass* calculates the biomass growth for a day after \[1\]\[2\]. +Input: + +- fPAR, the modified Photosynthetic Active Radiation for crops. +- Light Use Efficiency \[0.0-1.0\], in Uzbekistan cotton is at 1.9 most + of the time. +- Latitude \[0.0-90.0\], from *r.latlong*. +- DOY \[1-366\]. +- Transmissivity of the atmosphere single-way \[0.0-1.0\], mostly around + 0.7+ in clear sky. +- Water availability \[0.0-1.0\], possibly using direct output from + *i.eb.evapfr*. + +## NOTES + +*i.biomass* can use the output of *i.eb.evapfr* directly as water +availability input. + +## TODO + +Remove Latitude, DOY and Tsw from input and replace with a raster input +compatible with *r.sun* output. + +## REFERENCES + +\[1\] Bastiaanssen, W.G.M., Ali, S., 2002. A new crop yield forecasting +model based on satellite measurements applied across the Indus Basin, +Pakistan. Agriculture, Ecosystems and Environment, 94(3):321-340. +([PDF](https://edepot.wur.nl/206553)) + +\[2\] Chemin, Y., Platonov, A., Abdullaev, I., Ul-Hassan, M. 2005. +Supplementing farm level water productivity assessment by remote sensing +in transition economies. Water International. 30(4):513-521. + +## SEE ALSO + +*[i.eb.evapfr](i.eb.evapfr.md), [r.latlong](r.latlong.md), +[r.sun](r.sun.md)* + +## AUTHOR + +Yann Chemin, Bec de Mortagne, France diff --git a/imagery/i.cca/i.cca.md b/imagery/i.cca/i.cca.md new file mode 100644 index 00000000000..3994aff2309 --- /dev/null +++ b/imagery/i.cca/i.cca.md @@ -0,0 +1,59 @@ +## DESCRIPTION + +**i.cca** is an image processing program that takes any number of +(raster) band files and a signature file, and outputs the same number of +raster band files transformed to provide maximum separability of the +categories indicated by the signatures. This implementation of the +canonical components transformation is based on the algorithm contained +in the [LAS image processing +system](http://dbwww.essc.psu.edu/lasdoc/user/canal.html). CCA is also +known as "Canonical components transformation". + +Typically the user will use the *[g.gui.iclass](g.gui.iclass.md)* +program to collect a set of signatures and then pass those signatures +along with the raster band files to *i.cca*. The raster band file names +are specified on the command line by giving the group and subgroup that +were used to collect the signatures. + +The output raster map names are built by appending a ".1", ".2", etc. to +the output raster map name specified on the command line. + +### Parameters + +**group=***name* +Name of the [imagery](i.group.md) group to which the raster band files +used belong. + +**subgroup=***name* +Name of the [imagery](i.group.md) subgroup to which the raster band +files used belong. + +**signature=***name* +Name of an ASCII file containing spectral signatures. + +**output=***name* +Output raster map prefix name. The output raster map layer names are +built by appending a ".1", ".2", etc. onto the *output* name specified +by the user. + +## NOTES + +*i.cca* respects the current geographic region definition and the +current mask setting while performing the transformation. + +## REFERENCES + +Schowengerdt, Robert A. **Techniques for Image Processing and +Classification in Remote Sensing**, Academic Press, 1983. + +## SEE ALSO + +*[g.gui.iclass](g.gui.iclass.md), [i.gensig](i.gensig.md), +[i.cluster](i.cluster.md), [i.pca](i.pca.md), [r.covar](r.covar.md), +[r.mapcalc](r.mapcalc.md)* + +## AUTHORS + +David Satnik, GIS Laboratory, Central Washington University +Ali R. Vali, University of Texas +Semantic label support: Maris Nartiss, University of Latvia diff --git a/imagery/i.cluster/i.cluster.md b/imagery/i.cluster/i.cluster.md new file mode 100644 index 00000000000..7e0b7438ce8 --- /dev/null +++ b/imagery/i.cluster/i.cluster.md @@ -0,0 +1,251 @@ +## DESCRIPTION + +*i.cluster* performs the first pass in the two-pass unsupervised +classification of imagery, while the GRASS module +*[i.maxlik](i.maxlik.md)* executes the second pass. Both commands must +be run to complete the unsupervised classification. + +*i.cluster* is a clustering algorithm (a modification of the *k*-means +clustering algorithm) that reads through the (raster) imagery data and +builds pixel clusters based on the spectral reflectances of the pixels +(see Figure). The pixel clusters are imagery categories that can be +related to land cover types on the ground. The spectral distributions of +the clusters (e.g., land cover spectral signatures) are influenced by +six parameters set by the user. A relevant parameter set by the user is +the initial number of clusters to be discriminated. + + + +| | +|----------------------------------------------------------------------| +| *Fig.: Land use/land cover clustering of LANDSAT scene (simplified)* | + +*i.cluster* starts by generating spectral signatures for this number of +clusters and "attempts" to end up with this number of clusters during +the clustering process. The resulting number of clusters and their +spectral distributions, however, are also influenced by the range of the +spectral values (category values) in the image files and the other +parameters set by the user. These parameters are: the minimum cluster +size, minimum cluster separation, the percent convergence, the maximum +number of iterations, and the row and column sampling intervals. + +The cluster spectral signatures that result are composed of cluster +means and covariance matrices. These cluster means and covariance +matrices are used in the second pass (*[i.maxlik](i.maxlik.md)*) to +classify the image. The clusters or spectral classes result can be +related to land cover types on the ground. The user has to specify the +name of group file, the name of subgroup file, the name of a file to +contain result signatures, the initial number of clusters to be +discriminated, and optionally other parameters (see below) where the +*group* should contain the imagery files that the user wishes to +classify. The *subgroup* is a subset of this group. The user must create +a group and subgroup by running the GRASS program +*[i.group](i.group.md)* before running *i.cluster*. The subgroup should +contain only the imagery band files that the user wishes to classify. +Note that this subgroup must contain more than one band file. The +purpose of the group and subgroup is to collect map layers for +classification or analysis. The *signaturefile* is the file to contain +result signatures which can be used as input for +*[i.maxlik](i.maxlik.md)*. The classes value is the initial number of +clusters to be discriminated; any parameter values left unspecified are +set to their default values. + +For all raster maps used to generate signature file it is recommended to +have semantic label set. Use *[r.support](r.support.md)* to set semantc +labels of each member of the imagery group. Signatures generated for one +scene are suitable for classification of other scenes as long as they +consist of same raster bands (semantic labels match). If semantic labels +are not set, it will be possible to use obtained signature file to +classify only the same imagery group used for generating signatures. + +### Parameters + +**group=***name* +The name of the group file which contains the imagery files that the +user wishes to classify. + +**subgroup=***name* +The name of the subset of the group specified in group option, which +must contain only imagery band files and more than one band file. The +user must create a group and a subgroup by running the GRASS program +*[i.group](i.group.md)* before running *i.cluster*. + +**signaturefile=***name* +The name assigned to output signature file which contains signatures of +classes and can be used as the input file for the GRASS program +*[i.maxlik](i.maxlik.md)* for an unsupervised classification. + +**classes=***value* +The number of clusters that will initially be identified in the +clustering process before the iterations begin. + +**seed=***name* +The name of a seed signature file is optional. The seed signatures are +signatures that contain cluster means and covariance matrices which were +calculated prior to the current run of *i.cluster*. They may be acquired +from a previously run of *i.cluster* or from a supervised classification +signature training site section (e.g., using the signature file output +by *[g.gui.iclass](g.gui.iclass.md)*). The purpose of seed signatures is +to optimize the cluster decision boundaries (means) for the number of +clusters specified. + +**sample=***rows,cols* +These numbers are optional with default values based on the size of the +data set such that the total pixels to be processed is approximately +10,000 (consider round up). The smaller these numbers, the larger the +sample size used to generate the signatures for the classes defined. + +**iterations=***value* +This parameter determines the maximum number of iterations which is +greater than the number of iterations predicted to achieve the optimum +percent convergence. The default value is 30. If the number of +iterations reaches the maximum designated by the user; the user may want +to rerun *i.cluster* with a higher number of iterations (see +[*reportfile*](#reportfile)). +Default: 30 + +**convergence=***value* +A high percent convergence is the point at which cluster means become +stable during the iteration process. The default value is 98.0 percent. +When clusters are being created, their means constantly change as pixels +are assigned to them and the means are recalculated to include the new +pixel. After all clusters have been created, *i.cluster* begins +iterations that change cluster means by maximizing the distances between +them. As these means shift, a higher and higher convergence is +approached. Because means will never become totally static, a percent +convergence and a maximum number of iterations are supplied to stop the +iterative process. The percent convergence should be reached before the +maximum number of iterations. If the maximum number of iterations is +reached, it is probable that the desired percent convergence was not +reached. The number of iterations is reported in the cluster statistics +in the report file (see [*reportfile*](#reportfile)). +Default: 98.0 + +**separation=***value* +This is the minimum separation below which clusters will be merged in +the iteration process. The default value is 0.0. This is an +image-specific number (a "magic" number) that depends on the image data +being classified and the number of final clusters that are acceptable. +Its determination requires experimentation. Note that as the minimum +class (or cluster) separation is increased, the maximum number of +iterations should also be increased to achieve this separation with a +high percentage of convergence (see [*convergence*](#convergence)). +Default: 0.0 + +**min_size=***value* +This is the minimum number of pixels that will be used to define a +cluster, and is therefore the minimum number of pixels for which means +and covariance matrices will be calculated. +Default: 17 + +**reportfile=***name* +The reportfile is an optional parameter which contains the result, i.e., +the statistics for each cluster. Also included are the resulting percent +convergence for the clusters, the number of iterations that was required +to achieve the convergence, and the separability matrix. + +## NOTES + +### Sampling method + +*i.cluster* does not cluster all pixels, but only a sample (see +parameter **sample**). The result of that clustering is not that all +pixels are assigned to a given cluster; essentially, only signatures +which are representative of a given cluster are generated. When running +*i.cluster* on the same data asking for the same number of classes, but +with different sample sizes, likely slightly different signatures for +each cluster are obtained at each run. + +### Algorithm used for i.cluster + +The algorithm uses input parameters set by the user on the initial +number of clusters, the minimum distance between clusters, and the +correspondence between iterations which is desired, and minimum size for +each cluster. It also asks if all pixels to be clustered, or every "x"th +row and "y"th column (sampling), the correspondence between iterations +desired, and the maximum number of iterations to be carried out. + +In the 1st pass, initial cluster means for each band are defined by +giving the first cluster a value equal to the band mean minus its +standard deviation, and the last cluster a value equal to the band mean +plus its standard deviation, with all other cluster means distributed +equally spaced in between these. Each pixel is then assigned to the +class which it is closest to, distance being measured as Euclidean +distance. All clusters less than the user-specified minimum distance are +then merged. If a cluster has less than the user-specified minimum +number of pixels, all those pixels are again reassigned to the next +nearest cluster. New cluster means are calculated for each band as the +average of raster pixel values in that band for all pixels present in +that cluster. + +In the 2nd pass, pixels are then again reassigned to clusters based on +new cluster means. The cluster means are then again recalculated. This +process is repeated until the correspondence between iterations reaches +a user-specified level, or till the maximum number of iterations +specified is over, whichever comes first. + +## EXAMPLE + +Preparing the statistics for unsupervised classification of a LANDSAT +scene within North Carolina project: + +```bash +# Set computational region to match the scene +g.region raster=lsat7_2002_10 -p + +# store VIZ, NIR, MIR into group/subgroup (leaving out TIR) +i.group group=lsat7_2002 subgroup=res_30m \ + input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 + +# generate signature file and report +i.cluster group=lsat7_2002 subgroup=res_30m \ + signaturefile=cluster_lsat2002 \ + classes=10 reportfile=rep_clust_lsat2002.txt +``` + +To complete the unsupervised classification, *i.maxlik* is subsequently +used. See example in its manual page. + +The signature file obtained in the example above will allow to classify +the current imagery group only (lsat7_2002). If the user would like to +re-use the signature file for the classification of different imagery +group(s), they can set semantic labels for each group member beforehand, +i.e., before generating the signature files. Semantic labels are set by +means of *r.support* as shown below: + +```bash +# Define semantic labels for all LANDSAT bands +r.support map=lsat7_2002_10 semantic_label=TM7_1 +r.support map=lsat7_2002_20 semantic_label=TM7_2 +r.support map=lsat7_2002_30 semantic_label=TM7_3 +r.support map=lsat7_2002_40 semantic_label=TM7_4 +r.support map=lsat7_2002_50 semantic_label=TM7_5 +r.support map=lsat7_2002_61 semantic_label=TM7_61 +r.support map=lsat7_2002_62 semantic_label=TM7_62 +r.support map=lsat7_2002_70 semantic_label=TM7_7 +r.support map=lsat7_2002_80 semantic_label=TM7_8 +``` + +## SEE ALSO + +- [Image + classification](https://grasswiki.osgeo.org/wiki/Image_classification) + wiki page +- Historical reference also the GRASS GIS 4 [Image Processing + manual](https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf) + (PDF) +- [Wikipedia article on *k*-means + clustering](https://en.wikipedia.org/wiki/K-means_clustering) (note + that *i.cluster* uses a modification of the *k*-means clustering + algorithm) + +*[r.support](r.support.md), [g.gui.iclass](g.gui.iclass.md), +[i.group](i.group.md), [i.gensig](i.gensig.md), [i.maxlik](i.maxlik.md), +[i.segment](i.segment.md), [i.smap](i.smap.md), [r.kappa](r.kappa.md)* + +## AUTHORS + +Michael Shapiro, U.S. Army Construction Engineering Research +Laboratory +Tao Wen, University of Illinois at Urbana-Champaign, Illinois +Semantic label support: Maris Nartiss, University of Latvia diff --git a/imagery/i.eb.eta/i.eb.eta.md b/imagery/i.eb.eta/i.eb.eta.md new file mode 100644 index 00000000000..a1e7f760523 --- /dev/null +++ b/imagery/i.eb.eta/i.eb.eta.md @@ -0,0 +1,48 @@ +## DESCRIPTION + +*i.eb.eta* calculates the actual evapotranspiration (ETa ; mm/d) for +diurnal period after \[1\], implemented in \[3\]. It takes input of +Diurnal Net Radiation (see *r.sun*), evaporative fraction (see +*i.eb.evapfr*) and surface skin temperature. + +## NOTES + +Full ETa processing will need those: + +- *i.vi*, *i.albedo*, *r.latlong*, *i.emissivity* +- *i.evapo.potrad* (GRASS Addon) +- *i.eb.netrad*, *i.eb.soilheatflux*, *i.eb.hsebal01* +- *i.eb.evapfr*, *i.eb.eta* + +(for time integration: *i.evapo.time_integration*) + +For more details on the algorithms see \[1\]\[2\]\[3\]\[4\]. + +## REFERENCES + +\[1\] Bastiaanssen, W.G.M., 1995. Estimation of Land surface parameters +by remote sensing under clear-sky conditions. PhD thesis, Wageningen +University, Wageningen, The Netherlands. +([PDF](https://edepot.wur.nl/206553)) + +\[2\] Chemin Y., Alexandridis T.A., 2001. Improving spatial resolution +of ET seasonal for irrigated rice in Zhanghe, China. Asian Journal of +Geoinformatics. 5(1):3-11,2004. + +\[3\] Alexandridis T.K., Cherif I., Chemin Y., Silleos N.G., Stavrinos +E., Zalidis G.C. Integrated methodology for estimating water use in +Mediterranean agricultural areas. Remote Sensing. 2009, 1, 445-465. +([PDF](https://doi.org/10.3390/rs1030445)) + +\[4\] Chemin, Y., 2012. A Distributed Benchmarking Framework for Actual +ET Models, in: Irmak, A. (Ed.), Evapotranspiration - Remote Sensing and +Modeling. InTech. ([PDF](https://www.intechopen.com/chapters/26115)) + +## SEE ALSO + +*[r.sun](r.sun.md), [i.eb.evapfr](i.eb.evapfr.md), +[i.eb.netrad](i.eb.netrad.md)* + +## AUTHOR + +Yann Chemin, Asian Institute of Technology, Thailand diff --git a/imagery/i.eb.evapfr/i.eb.evapfr.md b/imagery/i.eb.evapfr/i.eb.evapfr.md new file mode 100644 index 00000000000..c08d2849e05 --- /dev/null +++ b/imagery/i.eb.evapfr/i.eb.evapfr.md @@ -0,0 +1,41 @@ +## DESCRIPTION + +*i.eb.evapfr* calculates the evaporative fraction after Bastiaanssen +1995. The main implementation follows Alexandridis et al. (2009). The +module takes as input the net radiation (see *r.sun*, *i.eb.netrad*), +soil heat flux (see *i.eb.soilheatflux*) and sensible heat flux (see +*i.eb.hsebal01*). A flag adds a root zone empirical soil moisture output +from the article of Bastiaanssen, et al. (2000). + +## REFERENCES + +Bastiaanssen, W.G.M., 1995. Estimation of Land surface parameters by +remote sensing under clear-sky conditions. PhD thesis, Wageningen +University, Wageningen, The Netherlands. +([PDF](https://edepot.wur.nl/206553)) + +Bastiaanssen, W.G.M., Molden, D.J., Makin, I.W., 2000. Remote sensing +for irrigated agriculture: examples from research and possible +applications. Agricultural water management 46.2: 137-155. + +Chemin Y., Alexandridis T.A., 2001. Improving spatial resolution of ET +seasonal for irrigated rice in Zhanghe, China. Asian Journal of +Geoinformatics. 5(1):3-11. + +Alexandridis T.K., Cherif I., Chemin Y., Silleos N.G., Stavrinos E., +Zalidis G.C., 2009. Integrated methodology for estimating water use in +Mediterranean agricultural areas. Remote Sensing. 1, 445-465. +([PDF](https://doi.org/10.3390/rs1030445)) + +Chemin, Y., 2012. A Distributed Benchmarking Framework for Actual ET +Models, in: Irmak, A. (Ed.), Evapotranspiration - Remote Sensing and +Modeling. InTech. ([PDF](https://www.intechopen.com/chapters/26115)) + +## SEE ALSO + +*[i.eb.hsebal01](i.eb.hsebal01.md), [i.eb.netrad](i.eb.netrad.md), +[i.eb.soilheatflux](i.eb.soilheatflux.md), [r.sun](r.sun.md)* + +## AUTHOR + +Yann Chemin, Asian Institute of Technology, Thailand diff --git a/imagery/i.eb.hsebal01/i.eb.hsebal01.md b/imagery/i.eb.hsebal01/i.eb.hsebal01.md new file mode 100644 index 00000000000..57f484b456a --- /dev/null +++ b/imagery/i.eb.hsebal01/i.eb.hsebal01.md @@ -0,0 +1,60 @@ +## DESCRIPTION + +*i.eb.hsebal01* will calculate the sensible heat flux map (h0), given +both maps of Net Radiation and soil Heat flux (Rn, g0) at instantaneous +time, the surface roughness (z0m), a map of the altitude corrected +temperature (t0dem), a point data of the frictional velocity (u\*), a +value of actual vapour pressure (ea\[KPa\]) and the (x,y) pairs for wet +and dry pixels. Full process will need those: + +- *i.vi*, *i.albedo*, *r.latlong*, *i.emissivity* +- *i.evapo.potrad* (GRASS Addon) +- *i.eb.netrad*, *i.eb.soilheatflux*, *i.eb.hsebal01* +- *i.eb.evapfr*, *i.eb.eta* + +(for time integration: *i.evapo.time_integration*) + +*i.eb.hsebal01* performs the computation of *sensible heat flux* +\[W/m2\] after Bastiaanssen, 1995 in \[1\], used in this form in 2001 by +\[2\]. Implemented in this code in \[3\]. + +## NOTES + +- z0m can be alculated by *i.eb.z0m* or *i.eb.z0m0* (GRASS Addons). +- ea can be calculated with standard meteorological data. + eoTmin=0.6108\*EXP(17.27\*Tmin/(Tmin+237.3)) + eoTmax=0.6108\*EXP(17.27\*Tmax/(Tmax+237.3)) + ea=(RH/100)/((eoTmin+eoTmax)/2) +- t0dem = surface temperature + (altitude \* 0.627 / 100) + +## REFERENCES + +\[1\] Bastiaanssen, W.G.M., 1995. Estimation of Land surface parameters +by remote sensing under clear-sky conditions. PhD thesis, Wageningen +University, Wageningen, The Netherlands. +([PDF](https://edepot.wur.nl/206553)) + +\[2\] Chemin Y., Alexandridis T.A., 2001. Improving spatial resolution +of ET seasonal for irrigated rice in Zhanghe, China. Asian Journal of +Geoinformatics. 5(1):3-11,2004. + +\[3\] Alexandridis T.K., Cherif I., Chemin Y., Silleos N.G., Stavrinos +E., Zalidis G.C. Integrated methodology for estimating water use in +Mediterranean agricultural areas. Remote Sensing. 2009, 1, 445-465. +([PDF](https://doi.org/10.3390/rs1030445)) + +\[4\] Chemin, Y., 2012. A Distributed Benchmarking Framework for Actual +ET Models, in: Irmak, A. (Ed.), Evapotranspiration - Remote Sensing and +Modeling. InTech. ([PDF](https://www.intechopen.com/chapters/26115)) + +## SEE ALSO + +*[i.eb.soilheatflux](i.eb.soilheatflux.md), +[i.eb.evapfr](i.eb.evapfr.md)* + +## AUTHOR + +Yann Chemin, International Rice Research Institute, Los Banos, The +Philippines. + +Contact: [Yann Chemin](mailto:yann.chemin@gmail.com) diff --git a/imagery/i.eb.netrad/i.eb.netrad.md b/imagery/i.eb.netrad/i.eb.netrad.md new file mode 100644 index 00000000000..1d1e2229d1b --- /dev/null +++ b/imagery/i.eb.netrad/i.eb.netrad.md @@ -0,0 +1,42 @@ +## DESCRIPTION + +*i.eb.netrad* calculates the net radiation at the time of satellite +overpass, the way it is in the SEBAL model of Bastiaanssen (1995). It +takes input of Albedo, NDVI, Surface Skin temperature, time of satellite +overpass, surface emissivity, difference of temperature from surface +skin and about 2 m height (dT), instantaneous satellite overpass +single-way atmospheric transmissivity (tsw), Day of Year (DOY), and sun +zenith angle. + +## NOTES + +In the old methods, dT was taken as flat images (dT=5.0), if you don't +have a dT map from ground data, you would want to try something in this +line, this is to calculate atmospherical energy balance. In the same +way, a standard tsw is used in those equations. Refer to `r_net.c` for +that and for other non-used equations, but stored in there for further +research convenience. + +## TODO + +Add more explanations. + +## REFERENCES + +- Bastiaanssen, W.G.M., 1995. Regionalization of surface flux densities + and moisture indicators in composite terrain; a remote sensing + approach under clear skies in mediterranean climates. PhD thesis, + Wageningen Agricultural Univ., The Netherland, 271 pp. + ([PDF](https://edepot.wur.nl/206553)) +- Chemin, Y., 2012. A Distributed Benchmarking Framework for Actual ET + Models, in: Irmak, A. (Ed.), Evapotranspiration - Remote Sensing and + Modeling. InTech. ([PDF](https://www.intechopen.com/chapters/26115)) + +## SEE ALSO + +*[i.eb.soilheatflux](i.eb.soilheatflux.md), +[i.eb.hsebal01](i.eb.hsebal01.md), [i.albedo](i.albedo.md)* + +## AUTHOR + +Yann Chemin, International Rice Research Institute, The Philippines diff --git a/imagery/i.eb.soilheatflux/i.eb.soilheatflux.md b/imagery/i.eb.soilheatflux/i.eb.soilheatflux.md new file mode 100644 index 00000000000..4f6d75b6669 --- /dev/null +++ b/imagery/i.eb.soilheatflux/i.eb.soilheatflux.md @@ -0,0 +1,59 @@ +## DESCRIPTION + +*i.eb.soilheatflux* calculates the soil heat flux approximation (g0) +after Bastiaanssen (1995). The main reference for implementation is +Alexandridis, 2009. It takes input of Albedo, NDVI, Surface Skin +temperature, Net Radiation (see *r.sun*), time of satellite overpass, +and a flag for the Roerink empirical modification from the HAPEX-Sahel +experiment. The "time of satellite overpass" map can be obtained as +follows: + +- MODIS: a related sub dataset is included in each HDF file, and simply + to be imported as a raster map; +- Landsat: to be generated as map from the overpass time stored in the + metadata file (given in Greenwich Mean Time - GMT), see below. + +For Landsat, the overpass map can be computed by using a two-step +method: + +```bash +# 1) extract the overpass time in GMT from metadata file + +i.landsat.toar -p input=dummy output=dummy2 \ + metfile=LC81250452013338LGN00_MTL.txt lsatmet=time +# ... in this example approx. 03:12am GMT + +# 2) create map for computational region of Landsat scene +g.region rast=LC81250452013338LGN00_B4 -p +r.mapcalc "overpasstime = 3.211328" +``` + +## REFERENCES + +Bastiaanssen, W.G.M., 1995. Estimation of Land surface parameters by +remote sensing under clear-sky conditions. PhD thesis, Wageningen +University, Wageningen, The Netherlands. +([PDF](https://edepot.wur.nl/206553)) + +Chemin Y., Alexandridis T.A., 2001. Improving spatial resolution of ET +seasonal for irrigated rice in Zhanghe, China. Asian Journal of +Geoinformatics. 5(1):3-11,2004. + +Alexandridis T.K., Cherif I., Chemin Y., Silleos N.G., Stavrinos E., +Zalidis G.C. Integrated methodology for estimating water use in +Mediterranean agricultural areas. Remote Sensing. 2009, 1, 445-465. +([PDF](https://doi.org/10.3390/rs1030445)) + +Chemin, Y., 2012. A Distributed Benchmarking Framework for Actual ET +Models, in: Irmak, A. (Ed.), Evapotranspiration - Remote Sensing and +Modeling. InTech. ([PDF](https://www.intechopen.com/chapters/26115)) + +## SEE ALSO + +*[r.sun](r.sun.md), [i.albedo](i.albedo.md), +[i.emissivity](i.emissivity.md), [i.eb.hsebal01](i.eb.hsebal01.md), +[i.eb.evapfr](i.eb.evapfr.md) [i.landsat.toar](i.landsat.toar.md)* + +## AUTHOR + +Yann Chemin, Asian Institute of Technology, Thailand diff --git a/imagery/i.emissivity/i.emissivity.md b/imagery/i.emissivity/i.emissivity.md new file mode 100644 index 00000000000..817bf5c5a80 --- /dev/null +++ b/imagery/i.emissivity/i.emissivity.md @@ -0,0 +1,40 @@ +## DESCRIPTION + +*i.emissivity* calculates the emissivity in the longwave radiation +spectrum, according to the semi-empirical equation related to NDVI by +Caselles et al. (1997), valid in the NDVI range of 0.16 to 0.74 +(Bastiaanssen, 1995). + +Caselles et al. (1997) give reference (in Table 3 and Figure 2) to both +the NDVI range used (0.15 - 0.71) and the corresponding emissivity range +used (0.97 - 0.99). + +The emissivity is the efficiency of longwave energy returning to the +atmosphere from the skin surface. The skin surface receives heat from +the thermal infrared radiation of the Sun, through atmospheric +interaction. A part is returned to the atmosphere fastly, and another +part is kept in the surface skin to be returned later. In more +scientific terms, the grey body radiation is equal to the black body +radiation times the emissivity. + +## REFERENCES + +- Bastiaanssen, W.G.M., 1995. Estimation of Land surface parameters by + remote sensing under clear-sky conditions. PhD thesis, Wageningen + University, Wageningen, The Netherlands. + ([PDF](https://edepot.wur.nl/206553)) +- Caselles, V., C. Coll, and E. Valor, 1997. Land surface emissivity and + temperature determination in the whole HAPEX-Sahel area from AVHRR + data. International Journal of Remote Sensing 18(5):1009-1027. +- Rubio, E., V. Caselles, and C. Badenas, 1997. Emissivity measurements + of several soils and vegetation types in the 8-14 µm wave band: + Analysis of two field methods. Remote Sensing of Environment 59(3): + 490-521. + +## SEE ALSO + +*[i.eb.netrad](i.eb.netrad.md)* + +## AUTHOR + +Yann Chemin, GRASS Development Team diff --git a/imagery/i.evapo.mh/i.evapo.mh.md b/imagery/i.evapo.mh/i.evapo.mh.md new file mode 100644 index 00000000000..43a55a3d93c --- /dev/null +++ b/imagery/i.evapo.mh/i.evapo.mh.md @@ -0,0 +1,28 @@ +## DESCRIPTION + +*i.evapo.mh* calculates the reference evapotranspiration (ET) after +Hargreaves et al. (1985), Hargreaves and Samani (1985) and the Modified +Hargreaves version found in Droogers and Allen (2002). + +## REFERENCES + +- Hargreaves GL, Hargreaves GH, Riley JP, 1985. Agricultural benefits + for Senegal River Basin. Journal of Irrigation and Drainange + Engineering, ASCE, 111(2):113-124. +- Droogers P, Allen RG, 2002. Towards a simplified global reference + evapotranspiration equation. Irrigation Science. +- Droogers, P., Allen RG. 2002. Estimating reference evapotranspiration + under inaccurate data conditions. Irrigation and Drainage Systems 16: + 33-45. +- Hargreaves GH, Samani ZA, 1985. Reference crop evapotranspiration from + ambient air temperature. American Society of Agricultural Engineers + (Microfiche collection)(USA). no. fiche no. 85-2517. + +## SEE ALSO + +*[i.evapo.pt](i.evapo.pt.md), [i.evapo.pm](i.evapo.pm.md), +[i.evapo.time](i.evapo.time.md), [r.sun](r.sun.md)* + +## AUTHOR + +Yann Chemin, GRASS Development team, 2007-2016 diff --git a/imagery/i.evapo.pm/i.evapo.pm.md b/imagery/i.evapo.pm/i.evapo.pm.md new file mode 100644 index 00000000000..96c6c8e9bad --- /dev/null +++ b/imagery/i.evapo.pm/i.evapo.pm.md @@ -0,0 +1,83 @@ +## DESCRIPTION + +*i.evapo.pm*, given the vegetation height (hc), humidity (RU), wind +speed at two meters height (WS), temperature (T), digital terrain model +(DEM), and net radiation (NSR) raster input maps, calculates the +potential evapotranspiration map (EPo). + +Optionally the user can activate a flag (-z) that allows him setting to +zero all of the negative evapotranspiration cells; in fact these +negative values motivated by the condensation of the air water vapour +content, are sometime undesired because they can produce computational +problems. The usage of the flag -n detect that the module is run in +night hours and the appropriate soil heat flux is calculated. + +The algorithm implements well known approaches: the hourly +Penman-Monteith method as presented in Allen et al. (1998) for land +surfaces and the Penman method (Penman, 1948) for water surfaces. + +Land and water surfaces are idenfyied by Vh: + +- where Vh gt 0 vegetation is present and evapotranspiration is + calculated; +- where Vh = 0 bare ground is present and evapotranspiration is + calculated; +- where Vh lt 0 water surface is present and evaporation is calculated. + +For more details on the algorithms see \[1,2,3\]. + +## NOTES + +Net solar radiation map in MJ/(m2\*h) can be computed from the +combination of the r.sun , run in mode 1, and the *r.mapcalc* commands. + +The sum of the three radiation components outputted by r.sun (beam, +diffuse, and reflected) multiplied by the Wh to Mj conversion factor +(0.0036) and optionally by a clear sky factor \[0-1\] allows the +generation of a map to be used as an NSR input for the *i.evapo.PM* +command. + +Example: + +```bash +r.sun -s elevin=dem aspin=aspect slopein=slope lin=2 albedo=alb_Mar \ + incidout=out beam_rad=beam diff_rad=diffuse refl_rad=reflected \ + day=73 time=13:00 dist=100; +r.mapcalc "NSR = 0.0036 * (beam + diffuse + reflected)" +``` + +## REFERENCES + +\[1\] Cannata M., 2006. [GIS embedded approach for Free & Open Source +Hydrological +Modelling](http://istgis.ist.supsi.ch:8001/geomatica/index.php?id=1). +PhD thesis, Department of Geodesy and Geomatics, Polytechnic of Milan, +Italy. + +\[2\] Allen, R.G., L.S. Pereira, D. Raes, and M. Smith. 1998. Crop +Evapotranspiration: Guidelines for computing crop water requirements. +Irrigation and Drainage Paper 56, Food and Agriculture Organization of +the United Nations, Rome, pp. 300 + +\[3\] Penman, H. L. 1948. Natural evaporation from open water, bare soil +and grass. Proc. Roy. Soc. London, A193, pp. 120-146. + +## SEE ALSO + +The [HydroFOSS](http://istgis.ist.supsi.ch:8001/geomatica/) project at +IST-SUPSI (Institute of Earth Sciences - University school of applied +science for the Southern Switzerland) +*[i.evapo.mh](i.evapo.mh.md), [i.evapo.time](i.evapo.time.md), +[r.sun](r.sun.md), [r.mapcalc](r.mapcalc.md)* + +## AUTHORS + +Original version of program: The +[HydroFOSS](http://istgis.ist.supsi.ch:8001/geomatica/index.php?id=1) +project, 2006, IST-SUPSI. +() *Massimiliano +Cannata, Scuola Universitaria Professionale della Svizzera Italiana - +Istituto Scienze della Terra* +*Maria A. Brovelli, Politecnico di Milano - Polo regionale di Como* + +Contact: [Massimiliano Cannata](mailto:massimiliano.cannata@supsi.ch) diff --git a/imagery/i.evapo.pt/i.evapo.pt.md b/imagery/i.evapo.pt/i.evapo.pt.md new file mode 100644 index 00000000000..9840d456dcf --- /dev/null +++ b/imagery/i.evapo.pt/i.evapo.pt.md @@ -0,0 +1,34 @@ +## DESCRIPTION + +*i.evapo.pt* Calculates the diurnal evapotranspiration after Prestley +and Taylor (1972). The Priestley-Taylor model (Priestley and Taylor, +1972) is a modification of Penman's more theoretical equation. + +## NOTES + +RNETD optional output from *i.evapo.potrad* is giving good results as +input for net radiation in this module. + +Alpha values: + +- 1.32 for estimates from vegetated areas as a result of the increase in + surface roughness (Morton, 1983; Brutsaert and Stricker, 1979) +- 1.26 is applicable in humid climates (De Bruin and Keijman, 1979; + Stewart and Rouse, 1976; Shuttleworth and Calder, 1979), and temperate + hardwood swamps (Munro, 1979) +- 1.74 has been recommended for estimating potential evapotranspiration + in more arid regions (ASCE, 1990). This worked well in Greece with + University of Thessaloniki. + +Alpha values extracted from: [Watflood +manual](http://www.civil.uwaterloo.ca/Watflood/Manual/02_03_1.htm). + +## SEE ALSO + +*[i.evapo.mh](i.evapo.mh.md), [i.evapo.pm](i.evapo.pm.md), +[i.evapo.time](i.evapo.time.md), [i.eb.netrad](i.eb.netrad.md), +[r.sun](r.sun.md)* + +## AUTHOR + +Yann Chemin, GRASS Development Team, 2007-08 diff --git a/imagery/i.evapo.time/i.evapo.time.md b/imagery/i.evapo.time/i.evapo.time.md new file mode 100644 index 00000000000..e673efca54d --- /dev/null +++ b/imagery/i.evapo.time/i.evapo.time.md @@ -0,0 +1,73 @@ +## DESCRIPTION + +*i.evapo.time* (i.evapo.time_integration) integrates ETa in time +following a reference ET (typically) from a set of meteorological +stations dataset. Inputs: + +- ETa images +- ETa images DOY (Day of Year) +- ETo images +- ETo DOYmin as a single value + +Method: + +1. each ETa pixel is divided by the same day ETo and become ETrF +2. each ETrF pixel is multiplied by the ETo sum for the representative + days +3. Sum all n temporal \[ETrF\*ETo_sum\] pixels to make a summed(ET) in + \[DOYmin;DOYmax\] + +representative days calculation: let assume i belongs to range +\[DOYmin;DOYmax\] + +```bash +DOYbeforeETa[i] = ( DOYofETa[i] - DOYofETa[i-1] ) / 2 +DOYafterETa[i] = ( DOYofETa[i+1] - DOYofETa[i] ) / 2 +``` + +## NOTES + +ETo images preparation: If you only have one meteorological station data +set, the easiest way is: + +```bash +n=0 +for ETo_val in Eto[1] Eto[2] ... +do + r.mapcalc "eto$n = $ETo_val" + `expr n = n + 1` +done +``` + +with Eto\[1\], Eto\[2\], etc being a simple copy and paste from your +data file of all ETo values separated by an empty space from each other. + +If you have several meteorological stations data, then you need to grid +them by generating Thiessen polygons or using different interpolation +methods for each day. + +For multi-year calculations, just continue incrementing DOY values above +366, it will continue working, up to maximum input of 400 satellite +images. + +![Temporal integration from a weather station](i_evapo_time.png) +*This is an example of a temporal integration from a weather station as +done by Chemin and Alexandridis (2004)* + +## References + +Chemin and Alexandridis, 2004. Spatial Resolution Improvement of +Seasonal Evapotranspiration for Irrigated Rice, Zhanghe Irrigation +District, Hubei Province, China. Asian Journal of Geoinformatics, Vol. +5, No. 1, September 2004 +([PDF](https://ikee.lib.auth.gr/record/270217/files/Chemin-Alexandridis.pdf)) + +## SEE ALSO + +*[i.eb.eta](i.eb.eta.md), [i.evapo.mh](i.evapo.mh.md), +[i.evapo.pt](i.evapo.pt.md), [i.evapo.pm](i.evapo.pm.md), +[r.sun](r.sun.md)* + +## AUTHOR + +Yann Chemin, International Rice Research Institute, The Philippines diff --git a/imagery/i.fft/i.fft.md b/imagery/i.fft/i.fft.md new file mode 100644 index 00000000000..98fa93f9128 --- /dev/null +++ b/imagery/i.fft/i.fft.md @@ -0,0 +1,56 @@ +## DESCRIPTION + +*i.fft* is an image processing program based on the FFT algorithm given +by Frigo et al. (1998), that processes a single input raster map layer +(**input**) and constructs the real and imaginary Fourier components in +frequency space. + +## NOTES + +The real and imaginary components are stored into the **real** and +**imaginary** raster map layers. In these raster map layers the low +frequency components are in the center and the high frequency components +are toward the edges. The **input** need not be square. A color table is +assigned to the resultant map layer. + +The current geographic region and mask settings are respected when +reading the input file. The presence of nulls or a mask will make the +resulting fast Fourier transform invalid. + +## EXAMPLE + +North Carolina example: + +```bash +g.region raster=lsat7_2002_70 +i.fft input=lsat7_2002_70 real=lsat7_2002_70.real imaginary=lsat7_2002_70.imag + +# set region to resulting FFT output map (due to new FFT coordinate space): +g.region raster=lsat7_2002_70.real -p +d.mon x0 +d.rast lsat7_2002_70.real +d.rast lsat7_2002_70.imag +``` + +## REFERENCES + +- M. Frigo and S. G. Johnson (1998): "FFTW: An Adaptive Software + Architecture for the FFT". See [www.FFTW.org](https://fftw.org): FFTW + is a C subroutine library for computing the Discrete Fourier Transform + (DFT) in one or more dimensions, of both real and complex data, and of + arbitrary input size. +- John A. Richards, 1986. Remote Sensing Digital Image Analysis, + Springer-Verlag. +- Personal communication, between program author and Ali R. Vali, Space + Research Center, [University of Texas](https://www.utexas.edu), + Austin, 1990. + +## SEE ALSO + +*[i.cca](i.cca.md), [g.gui.iclass](g.gui.iclass.md), +[i.ifft](i.ifft.md), [i.pca](i.pca.md)* + +## AUTHORS + +David Satnik, GIS Laboratory, Central Washington University +Glynn Clements (FFTW support) diff --git a/imagery/i.gensig/i.gensig.md b/imagery/i.gensig/i.gensig.md new file mode 100644 index 00000000000..f14827d37b1 --- /dev/null +++ b/imagery/i.gensig/i.gensig.md @@ -0,0 +1,106 @@ +## DESCRIPTION + +*i.gensig* is a non-interactive method for generating input into +*[i.maxlik](i.maxlik.md)*. It can be used as the first pass in the GRASS +two-pass classification process (instead of *[i.cluster](i.cluster.md)* +or *[g.gui.iclass](g.gui.iclass.md))*. It reads a raster map layer, +called the training map, which has some of the pixels or regions already +classified. *i.gensig* will then extract spectral signatures from an +image based on the classification of the pixels in the training map and +make these signatures available to *[i.maxlik](i.maxlik.md)*. + +The user would then execute the GRASS program *[i.maxlik](i.maxlik.md)* +to actually create the final classified map. + +This module generates signature files of type "sig". Use module +[i.signatures](i.signatures.md) to manage generated signature files. + +All raster maps used to generate signature file can have semantic label +set. Use *[r.support](r.support.md)* to set semantic labels of each +member of the imagery group. Signatures generated for one scene are +suitable for classification of other scenes as long as they consist of +same raster bands (semantic labels match). + +## OPTIONS + +### Parameters + +**trainingmap=***name* +ground truth training map + +This map must be prepared by the user in advance using vector or raster +digitizer. Of course other methods could be devised by the user for +creating this training map - *i.gensig* makes no assumption about the +origin of this map layer. It simply creates signatures for the classes +defined in the training map for the image to be classified (the image is +specified in other options - see below). The *[wxGUI vector +digitizer](wxGUI.vdigit.md)* can be used for interactively creating the +training map. + +**group=***name* +imagery group + +This is the name of the group that contains the band files which +comprise the image to be analyzed. The *[i.group](i.group.md)* command +is used to construct groups of raster layers which comprise an image. + +**subgroup=***name* +subgroup containing image files + +This names the subgroup within the group that selects a subset of the +bands to be analyzed. The *[i.group](i.group.md)* command is also used +to prepare this subgroup. The subgroup mechanism allows the user to +select a subset of all the band files that form an image. + +**signaturefile=***name* +resultant signature file + +This is the resultant signature file (containing the means and +covariance matrices) for each class in the training map that is +associated with the band files in the subgroup select (see +[above](#subgroup)). Resultant singature file can be used with any other +imagery group as long as semantic labels match. + +## NOTES + +The structure of the SIG files generated by *i.gensig* is as follows +(ASCII file, used internally by *i.maxlik*): +*Note: the line numbers are not present in the file but have been added +here for explanation only*: + +SIG file "lsat7_2000_gensig": + +```bash + 1 1 + 2 # + 3 Semantic_label1 + 4 #water + 5 4186 + 6 67.9508 48.7346 37.8915 15.3129 13.8473 12.0855 + 7 1.74334 + 8 0.439504 2.07267 + 9 0.662523 1.63501 4.21189 +10 0.530339 2.40757 5.52857 22.433 +11 0.561184 2.30762 5.18846 20.5364 20.4926 +12 0.393218 1.2184 2.63628 9.61528 9.36025 5.85314 +``` + +- Line 1: version number (currently always 1) +- Line 2: text label +- Line 3: Space separated list of semantic labels +- Line 4: text label of class +- Line 5: number of points in class +- Line 6: mean values per band of the class +- Line 7-12: (semi)-matrix of band-band covariance + +## SEE ALSO + +*[r.support](r.support.md), [g.gui.iclass](g.gui.iclass.md), +[i.group](i.group.md), [i.cca](i.cca.md), [i.maxlik](i.maxlik.md), +[i.smap](i.smap.md), [r.info](r.info.md), [r.univar](r.univar.md), +[wxGUI vector digitizer](wxGUI.vdigit.md)* + +## AUTHORS + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory +Semantic label support: Maris Nartiss, University of Latvia diff --git a/imagery/i.gensigset/i.gensigset.md b/imagery/i.gensigset/i.gensigset.md new file mode 100644 index 00000000000..865a349d63b --- /dev/null +++ b/imagery/i.gensigset/i.gensigset.md @@ -0,0 +1,161 @@ +## DESCRIPTION + +*i.gensigset* is a non-interactive method for generating input into +*[i.smap](i.smap.md).* It is used as the first pass in the a two-pass +classification process. It reads a raster map layer, called the training +map, which has some of the pixels or regions already classified. +*i.gensigset* will then extract spectral signatures from an image based +on the classification of the pixels in the training map and make these +signatures available to *[i.smap](i.smap.md).* + +The user would then execute the GRASS program *[i.smap](i.smap.md)* to +create the final classified map. + +This module generates signature files of type "sigset". Use module +[i.signatures](i.signatures.md) to manage generated signature files. + +For all raster maps used to generate signature file it is recommended to +have semantic label set. Use *[r.support](r.support.md)* to set semantic +labels of each member of the imagery group. Signatures generated for one +scene are suitable for classification of other scenes as long as they +consist of same raster bands (semantic labels match). If semantic labels +are not set, it will be possible to use obtained signature file to +classify only the same imagery group used for generating signatures. + +An usage example can be found in [i.smap](i.smap.md) documentation. + +## OPTIONS + +### Parameters + +**trainingmap=***name* +ground truth training map + +This raster layer, supplied as input by the user, has some of its pixels +already classified, and the rest (probably most) of the pixels +unclassified. Classified means that the pixel has a non-zero value and +unclassified means that the pixel has a zero value. + +This map must be prepared by the user in advance by using a combination +of *[wxGUI vector digitizer](wxGUI.vdigit.md)* and +*[v.to.rast](v.to.rast.md)*, or some other import/development process +(e.g., *[v.transects](v.transects.md))* to define the areas +representative of the classes in the image. + +At present, there is no fully-interactive tool specifically designed for +producing this layer. + +**group=***name* +imagery group + +This is the name of the group that contains the band files which +comprise the image to be analyzed. The *[i.group](i.group.md)* command +is used to construct groups of raster layers which comprise an image. + +**subgroup=***name* +subgroup containing image files + +This names the subgroup within the group that selects a subset of the +bands to be analyzed. The *[i.group](i.group.md)* command is also used +to prepare this subgroup. The subgroup mechanism allows the user to +select a subset of all the band files that form an image. + +**signaturefile=***name* +resultant signature file + +This is the resultant signature file (containing the means and +covariance matrices) for each class in the training map that is +associated with the band files in the subgroup selected. + +**maxsig=***value* +maximum number of sub-signatures in any class +default: 5 + +The spectral signatures which are produced by this program are "mixed" +signatures (see [NOTES](#notes)). Each signature contains one or more +subsignatures (represeting subclasses). The algorithm in this program +starts with a maximum number of subclasses and reduces this number to a +minimal number of subclasses which are spectrally distinct. The user has +the option to set this starting value with this option. + +## NOTES + +The algorithm in *i.gensigset* determines the parameters of a spectral +class model known as a Gaussian mixture distribution. The parameters are +estimated using multispectral image data and a training map which labels +the class of a subset of the image pixels. The mixture class parameters +are stored as a class signature which can be used for subsequent +segmentation (i.e., classification) of the multispectral image. + +The Gaussian mixture class is a useful model because it can be used to +describe the behavior of an information class which contains pixels with +a variety of distinct spectral characteristics. For example, forest, +grasslands or urban areas are examples of information classes that a +user may wish to separate in an image. However, each of these +information classes may contain subclasses each with its own distinctive +spectral characteristic. For example, a forest may contain a variety of +different tree species each with its own spectral behavior. + +The objective of mixture classes is to improve segmentation performance +by modeling each information class as a probabilistic mixture with a +variety of subclasses. The mixture class model also removes the need to +perform an initial unsupervised segmentation for the purposes of +identifying these subclasses. However, if misclassified samples are used +in the training process, these erroneous samples may be grouped as a +separate undesired subclass. Therefore, care should be taken to provided +accurate training data. + +This clustering algorithm estimates both the number of distinct +subclasses in each class, and the spectral mean and covariance for each +subclass. The number of subclasses is estimated using Rissanen's minimum +description length (MDL) criteria \[[1](#rissanen83)\]. This criteria +attempts to determine the number of subclasses which "best" describe the +data. The approximate maximum likelihood estimates of the mean and +covariance of the subclasses are computed using the expectation +maximization (EM) algorithm \[[2](#dempster77),[3](#redner84)\]. + +## WARNINGS + +If warnings like this occur, reducing the remaining classes to 0: + +```bash +... +WARNING: Removed a singular subsignature number 1 (4 remain) +WARNING: Removed a singular subsignature number 1 (3 remain) +WARNING: Removed a singular subsignature number 1 (2 remain) +WARNING: Removed a singular subsignature number 1 (1 remain) +WARNING: Unreliable clustering. Try a smaller initial number of clusters +WARNING: Removed a singular subsignature number 1 (-1 remain) +WARNING: Unreliable clustering. Try a smaller initial number of clusters +Number of subclasses is 0 +``` + +then the user should check for: + +- the range of the input data should be between 0 and 100 or 255 but not + between 0.0 and 1.0 (*r.info* and *r.univar* show the range) +- the training areas need to contain a sufficient amount of pixels + +## REFERENCES + +- J. Rissanen, "A Universal Prior for + Integers and Estimation by Minimum Description Length," *Annals of + Statistics,* vol. 11, no. 2, pp. 417-431, 1983. +- A. Dempster, N. Laird and D. Rubin, + "Maximum Likelihood from Incomplete Data via the EM Algorithm," *J. + Roy. Statist. Soc. B,* vol. 39, no. 1, pp. 1-38, 1977. +- E. Redner and H. Walker, "Mixture + Densities, Maximum Likelihood and the EM Algorithm," *SIAM Review,* + vol. 26, no. 2, April 1984. + +## SEE ALSO + +*[r.support](r.support), [i.group](i.group.md), [i.smap](i.smap.md), +[r.info](r.info.md), [r.univar](r.univar.md), [wxGUI vector +digitizer](wxGUI.vdigit.md)* + +## AUTHORS + +Charles Bouman, School of Electrical Engineering, Purdue University +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory +Semantic label support: Maris Nartiss, University of Latvia diff --git a/imagery/i.group/i.group.md b/imagery/i.group/i.group.md new file mode 100644 index 00000000000..0dc352f15f0 --- /dev/null +++ b/imagery/i.group/i.group.md @@ -0,0 +1,44 @@ +## DESCRIPTION + +*i.group* allows the user to collect raster map layers in an imagery +group by assigning them to user-named subgroups or other groups. This +enables the user to run analyses on any combination of the raster map +layers in a group. The user creates the groups and subgroups and selects +the raster map layers that are to reside in them. Imagery analysis +programs like *[g.gui.gcp](g.gui.gcp.md)*, *[i.rectify](i.rectify.md)*, +*[i.ortho.photo](i.ortho.photo.md)* and others ask the user for the name +of an imagery group whose data are to be analyzed. Imagery analysis +programs like *[i.cluster](i.cluster.md)* and *[i.maxlik](i.maxlik.md)* +ask the user for the imagery group and imagery subgroup whose data are +to be analyzed. + +## NOTES + +The *i.group* options are only available for imagery map layers in the +current LOCATION_NAME. + +Subgroup names may not contain more than 12 characters. + +### EXAMPLE + +This example runs in the "landsat" mapset of the North Carolina sample +dataset. The following command creates a group and subgroup containing +only the visible light bands of Landsat-7: + +```bash +i.group group=vis_bands subgroup=vis_bands input=lsat7_2000_10,lsat7_2000_20,lsat7_2000_30 +``` + +## SEE ALSO + +The GRASS 4 *[Image Processing +manual](https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf)* + +*[g.gui.gcp](g.gui.gcp.md), [i.cluster](i.cluster.md), +[i.maxlik](i.maxlik.md), [i.rectify](i.rectify.md), +[i.ortho.photo](i.ortho.photo.md)* + +## AUTHORS + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory +Parser support: Bob Covill (Tekmap, Canada) diff --git a/imagery/i.his.rgb/i.his.rgb.md b/imagery/i.his.rgb/i.his.rgb.md new file mode 100644 index 00000000000..49084a8e160 --- /dev/null +++ b/imagery/i.his.rgb/i.his.rgb.md @@ -0,0 +1,31 @@ +## DESCRIPTION + +*i.his.rgb* is an image processing program that processes three input +raster map layers as hue, intensity and saturation components and +produces three output raster map layers representing the red, green and +blue components of this data. The output raster map layers are created +by a standard hue-intensity-saturation (HIS) to red-green-blue (RGB) +color transformation. Each output raster map layer is given a linear +gray scale color table. The current geographic region and mask settings +are respected. + +## NOTES + +It is not possible to process three bands with *i.his.rgb* and then +exactly recover the original bands with *i.rgb.his*. This is due to loss +of precision because of integer computations and rounding. Tests have +shown that more than 70% of the original cell values will be reproduced +exactly after transformation in both directions and that 99% will be +within plus or minus 1. A few cell values may differ significantly from +their original values. + +## SEE ALSO + +*[i.rgb.his](i.rgb.his.md), [r.colors](r.colors.md)* + +## AUTHOR + +David Satnik, GIS Laboratory, Central Washington University + +with acknowledgements to Ali Vali, Univ. of Texas Space Research Center, +for the core routine. diff --git a/imagery/i.ifft/i.ifft.md b/imagery/i.ifft/i.ifft.md new file mode 100644 index 00000000000..d8e87e9213f --- /dev/null +++ b/imagery/i.ifft/i.ifft.md @@ -0,0 +1,41 @@ +## DESCRIPTION + +*i.ifft* is an image processing program based on the algorithm given by +Frigo et al. (1998), that converts real and imaginary frequency space +images (produced by *[i.fft](i.fft.md)*) into a normal image. + +## NOTES + +The current mask is respected when reading the real and imaginary +component files; thus, creating a mask is a primary step for selecting +the portion of the frequency space data to be included in the inverse +transform. The module *[wxGUI vector digitizer](wxGUI.vdigit.md)* can be +used to create masks while viewing the real or imaginary component +image. Alternatively *r.circle* can be used to generate high-, low- and +donut filters specifying the DC point as circle/ring center. When +*i.ifft* is executed, it (automatically) uses the same GRASS region +definition setting that was used during the original transformation done +with *[i.fft](i.fft.md)*. + +## REFERENCES + +- M. Frigo and S. G. Johnson (1998): "FFTW: An Adaptive Software + Architecture for the FFT". See [www.fftw.org](https://fftw.org/): FFTW + is a C subroutine library for computing the Discrete Fourier Transform + (DFT) in one or more dimensions, of both real and complex data, and of + arbitrary input size. +- Richards, J.A (1986): **Remote Sensing Digital Image Analysis**, + Springer-Verlag, 1986. +- Personal communication, between program author and Ali R. Vali, Space + Research Center, University of Texas, Austin, 1990. + +## SEE ALSO + +*[i.cca](i.cca.md), [g.gui.iclass](g.gui.iclass.md), [i.fft](i.fft.md), +[i.pca](i.pca.md), [r.circle](r.circle.md), [wxGUI vector +digitizer](wxGUI.vdigit.md)* + +## AUTHORS + +David Satnik, GIS Laboratory, Central Washington University +Glynn Clements (FFTW support) diff --git a/imagery/i.landsat.acca/i.landsat.acca.md b/imagery/i.landsat.acca/i.landsat.acca.md new file mode 100644 index 00000000000..240631ce764 --- /dev/null +++ b/imagery/i.landsat.acca/i.landsat.acca.md @@ -0,0 +1,52 @@ +## DESCRIPTION + +*i.landsat.acca* implements the **Automated Cloud-Cover Assessment** +(ACCA) Algorithm from Irish (2000) with the constant values for pass +filter one from Irish et al. (2006). To do this, it needs Landsat band +numbers 2, 3, 4, 5, and 6 (or band 61 for Landsat-7 ETM+) which have +already been processed from DN into reflectance and band-6 temperature +with *[i.landsat.toar](i.landsat.toar.md)*). + +The ACCA algorithm gives good results over most of the planet with the +exception of ice sheets because ACCA operates on the premise that clouds +are colder than the land surface they cover. The algorithm was designed +for Landsat-7 ETM+ but because reflectance is used it is also useful for +Landsat-4/5 TM. + +## NOTES + +*i.landsat.acca* works in the current region settings. + +## EXAMPLES + +Run the standard ACCA algorithm with filling of small cloud holes (the +**-f** flag): With per-band reflectance raster maps named +`226_62.toar.1, 226_62.toar.2, ...` and LANDSAT-7 thermal band +`226_62.toar.61`, outputting to a new raster map named `226_62.acca`: + +```bash +i.landsat.toar sensor=7 gain=HHHLHLHHL date=2003-04-07 \ + product_date=2008-11-27 band_prefix=226_62 solar_elevation=49.51654 + +i.landsat.acca -f band_prefix=226_62.toar output=226_62.acca +``` + +## REFERENCES + +- Irish R.R., Barker J.L., Goward S.N., and Arvidson T., 2006. + Characterization of the Landsat-7 ETM+ Automated Cloud-Cover + Assessment (ACCA) Algorithm. Photogrammetric Engineering and Remote + Sensing vol. 72(10): 1179-1188. +- Irish, R.R., 2000. Landsat 7 Automatic Cloud Cover Assessment. In S.S. + Shen and M.R. Descour (Eds.): Algorithms for Multispectral, + Hyperspectral, and Ultraspectral Imagery VI. Proceedings of SPIE, + 4049: 348-355. + +## SEE ALSO + +*[i.atcorr](i.atcorr.md), [i.landsat.toar](i.landsat.toar.md)* + +## AUTHOR + +E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and +Environmental Management, University of León, Spain diff --git a/imagery/i.landsat.toar/i.landsat.toar.md b/imagery/i.landsat.toar/i.landsat.toar.md new file mode 100644 index 00000000000..a0734d8624c --- /dev/null +++ b/imagery/i.landsat.toar/i.landsat.toar.md @@ -0,0 +1,255 @@ +## DESCRIPTION + +*i.landsat.toar* is used to transform the calibrated digital number of +Landsat imagery products to top-of-atmosphere radiance or +top-of-atmosphere reflectance and temperature (band 6 of the sensors TM +and ETM+). Optionally, it can be used to calculate the at-surface +radiance or reflectance with atmospheric correction (DOS method). + +Usually, to do so the production date, the acquisition date, and the +solar elevation are needed. Moreover, for Landsat-7 ETM+ it is also +needed the gain (high or low) of the nine respective bands. + +Optionally (recommended), the data can be read from metadata file (.met +or MTL.txt) for all Landsat MSS, TM, ETM+ and OLI/TIRS. However, if the +solar elevation is given the value of the metadata file is overwritten. +This is necessary when the data in the .met file is incorrect or not +accurate. Also, if acquisition or production dates are not found in the +metadata file then the command line values are used. + +**Attention**: Any null value or smaller than QCALmin in the input +raster is set to null in the output raster and it is not included in the +equations. + +**Attention**: This module does **not** respect the current region +settings, in order to have the largest possible sample of pixels from +where to get the darkest one of the scene and perform the DOS +correction. To limit the results to a custom region, the user is advised +to clip the results (with [r.clip](r.clip.md), for instance) or to +define the region first, import the images with region cropping, and +then running the module. + +## Uncorrected at-sensor values (method=uncorrected, default) + +The standard geometric and radiometric corrections result in a +calibrated digital number (QCAL = DN) images. To further standardize the +impact of illumination geometry, the QCAL images are first converted +first to at-sensor radiance and then to at-sensor reflectance. The +thermal band is first converted from QCAL to at-sensor radiance, and +then to effective at-sensor temperature in Kelvin degrees. + +Radiometric calibration converts QCAL to **at-sensor radiance**, a +radiometric quantity measured in W/(m² \* sr \* µm) using the equations: + +- gain = (Lmax - Lmin) / (QCALmax - QCALmin) +- bias = Lmin - gain \* QCALmin +- radiance = gain \* QCAL + bias + +where, *Lmax* and *Lmin* are the calibration constants, and *QCALmax* +and *QCALmin* are the highest and the lowest points of the range of +rescaled radiance in QCAL. + +Then, to calculate **at-sensor reflectance** the equations are: + +- sun_radiance = \[Esun \* sin(e)\] / (PI \* d^2) +- reflectance = radiance / sun_radiance + +where, *d* is the earth-sun distance in astronomical units, *e* is the +solar elevation angle, and *Esun* is the mean solar exoatmospheric +irradiance in W/(m² \* µm). + +## Simplified at-surface values (method=dos\[1-4\]) + +Atmospheric correction and reflectance calibration remove the path +radiance, i.e. the stray light from the atmosphere, and the spectral +effect of solar illumination. To output these simple **at-surface +radiance** and **at-surface reflectance**, the equations are (not for +thermal bands): + +- sun_radiance = TAUv \* \[Esun \* sin(e) \* TAUz + Esky\] / (PI \* d^2) +- radiance_path = radiance_dark - percent \* sun_radiance +- radiance = (at-sensor_radiance - radiance_path) +- reflectance = radiance / sun_radiance + +where, *percent* is a value between 0.0 and 1.0 (usually 0.01), *Esky* +is the diffuse sky irradiance, *TAUz* is the atmospheric transmittance +along the path from the sun to the ground surface, and *TAUv* is the +atmospheric transmittance along the path from the ground surface to the +sensor. *radiance_dark* is the at-sensor radiance calculated from the +darkest object, i.e. DN with a least 'dark_parameter' (usually 1000) +pixels for the entire image. The values are, + +- DOS1: TAUv = 1.0, TAUz = 1.0 and Esky = 0.0 +- DOS2: TAUv = 1.0, Esky = 0.0, and TAUz = sin(e) for all bands with + maximum wave length less than 1. (i.e. bands 4-6 MSS, 1-4 TM, and 1-4 + ETM+) other bands TAUz = 1.0 +- DOS3: TAUv = exp\[-t/cos(sat_zenith)\], TAUz = exp\[-t/sin(e)\], Esky + = rayleigh +- DOS4: TAUv = exp\[-t/cos(sat_zenith)\], TAUz = exp\[-t/sin(e)\], Esky + = PI \* radiance_dark + +**Attention**: Output radiance remain untouched (i.e. no set to 0.0 when +it is negative) then they are possible negative values. However, output +reflectance is set to 0.0 when is obtained a negative value. + +## NOTES + +The output raster cell values can be rescaled with the **scale** +parameter (e.g., with 100 in case of using reflectance output in +*i.gensigset*). + +### On Landsat-8 metadata file + +NASA reports a structure of the L1G Metadata file +([LDCM-DFCB-004.pdf](http://landsat.usgs.gov/documents/LDCM-DFCB-004.pdf)) +for Landsat Data Continuity Mission (i.e. Landsat-8). + +NASA retains in MIN_MAX_RADIANCE group the necessary information to +transform Digital Numbers (DN) in radiance values. Then, +*i.landsat.toar* replaces the possible standard values with the metadata +values. The results match with the values reported by the metada file in +RADIOMETRIC_RESCALING group. + +Also, NASA reports the same values of reflectance for all bands in +max-min values and in gain-bias values. This is strange that all bands +have the same range of reflectance. Also, they wrote in the web page as +to calculate reflectance directly from DN, first with +RADIOMETRIC_RESCALING values and second divided by sin(sun_elevation). + +This is a simple rescaling + +- reflectance = radiance / sun_radiance = (DN \* RADIANCE_MULT + + RADIANCE_ADD) / sun_radiance +- now reflectance = DN \* REFLECTANCE_MULT + REFLECTANCE_ADD +- then REFLECTANCE_MULT = RADIANCE_MULT / sun_radiance +- and REFLECTANCE_ADD = RADIANCE_ADD / sun_radiance + +The problem arises when we need ESUN values (not provided) to compute +sun_radiance and DOS. We assume that REFLECTANCE_MAXIMUM corresponds to +the RADIANCE_MAXIMUM, then + +- REFLECTANCE_MAXIMUM / sin(e) = RADIANCE_MAXIMUM / sun_radiance +- Esun = (PI \* d^2) \* RADIANCE_MAXIMUM / REFLECTANCE_MAXIMUM + +where *d* is the earth-sun distance provided by metadata file or +computed inside the program. + +The *i.landsat.toar* reverts back the NASA rescaling to continue using +Lmax, Lmin, and Esun values to compute the constant to convert DN to +radiance and radiance to reflectance with the "traditional" equations +and simple atmospheric corrections. **Attention**: When MAXIMUM values +are not provided, *i.landsat.toar* tries to calculate Lmax, Lmin, and +Esun from RADIOMETRIC_RESCALING (in tests the results were the same). + +### Calibration constants + +In verbose mode (flag **--verbose**), the program write basic satellite +data and the parameters used in the transformations. + +Production date is not an exact value but it is necessary to apply +correct calibration constants, which were changed in the dates: + +- Landsat-1 MSS: never +- Landsat-2 MSS: July 16, 1975 +- Landsat-3 MSS: June 1, 1978 +- Landsat-4 MSS: August 26, 1982 and April 1, 1983 +- Landsat-4 TM: August 1, 1983 and January 15, 1984 +- Landsat-5 MSS: April 6, 1984 and November 9, 1984 +- Landsat-5 TM: May 4, 2003 and April, 2 2007 +- Landsat-7 ETM+: July 1, 2000 +- Landsat-8 OLI/TIRS: launched in 2013 + +## EXAMPLES + +### Metadata file examples + +Transform digital numbers of Landsat-7 ETM+ in band rasters 203_30.1, +203_30.2 \[...\] to uncorrected at-sensor reflectance in output files +203_30.1_toar, 203_30.2_toar \[...\] and at-sensor temperature in output +files 293_39.61_toar and 293_39.62_toar: + +```bash +i.landsat.toar input=203_30. output=_toar \ + metfile=p203r030_7x20010620.met +``` + +or + +```bash +i.landsat.toar input=L5121060_06020060714. \ + output=L5121060_06020060714_toar \ + metfile=L5121060_06020060714_MTL.txt +``` + +or + +```bash +i.landsat.toar input=LC80160352013134LGN03_B output=toar \ + metfile=LC80160352013134LGN03_MTL.txt sensor=oli8 date=2013-05-14 +``` + +### DOS1 example + +DN to reflectance using DOS1: + +```bash +# rename channels or make a copy to match i.landsat.toar's input scheme: +g.copy raster=lsat7_2002_10,lsat7_2002.1 +g.copy raster=lsat7_2002_20,lsat7_2002.2 +g.copy raster=lsat7_2002_30,lsat7_2002.3 +g.copy raster=lsat7_2002_40,lsat7_2002.4 +g.copy raster=lsat7_2002_50,lsat7_2002.5 +g.copy raster=lsat7_2002_61,lsat7_2002.61 +g.copy raster=lsat7_2002_62,lsat7_2002.62 +g.copy raster=lsat7_2002_70,lsat7_2002.7 +g.copy raster=lsat7_2002_80,lsat7_2002.8 +``` + +Calculation of reflectance values from DN using DOS1 (metadata obtained +from +[p016r035_7x20020524.met.gz](https://grassbook.org/wp-content/uploads/ncexternal/landsat/2002/p016r035_7x20020524.met.gz)): + +```bash +i.landsat.toar input=lsat7_2002. output=lsat7_2002_toar. sensor=tm7 \ + method=dos1 date=2002-05-24 sun_elevation=64.7730999 \ + product_date=2004-02-12 gain=HHHLHLHHL +``` + +The resulting Landsat channels are named +`lsat7_2002_toar.1 .. lsat7_2002_toar.8`. + +## REFERENCES + +- Chander G., B.L. Markham and D.L. Helder, 2009: Remote Sensing of + Environment, vol. 113 +- Chander G.H. and B. Markham, 2003: IEEE Transactions On Geoscience And + Remote Sensing, vol. 41, no. 11. +- Chavez P.S., jr. 1996: Image-based atmospheric corrections - Revisited + and Improved. Photogrammetric Engineering and Remote Sensing 62(9): + 1025-1036. +- Huang et al: At-Satellite Reflectance, 2002: A First Order + Normalization Of Landsat 7 ETM+ Images. +- R. Irish: [Landsat 7. Science Data Users + Handbook](http://landsathandbook.gsfc.nasa.gov/orbit_coverage/). + February 17, 2007; 15 May 2011. +- Markham B.L. and J.L. Barker, 1986: Landsat MSS and TM + Post-Calibration Dynamic Ranges, Exoatmospheric Reflectances and + At-Satellite Temperatures. EOSAT Landsat Technical Notes, No. 1. +- Moran M.S., R.D. Jackson, P.N. Slater and P.M. Teillet, 1992: Remote + Sensing of Environment, vol. 41. +- Song et al, 2001: Classification and Change Detection Using Landsat TM + Data, When and How to Correct Atmospheric Effects? Remote Sensing of + Environment, vol. 75. + +## SEE ALSO + +*[i.atcorr](i.atcorr.md), [i.colors.enhance](i.colors.enhance.md), +[r.mapcalc](r.mapcalc.md), [r.in.gdal](r.in.gdal.md)* + +[Landsat Data +Dictionary](https://lta.cr.usgs.gov/DD/landsat_dictionary.html) by USGS + +## AUTHOR + +E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and +Environmental Management, University of León, Spain diff --git a/imagery/i.maxlik/i.maxlik.md b/imagery/i.maxlik/i.maxlik.md new file mode 100644 index 00000000000..ff904133896 --- /dev/null +++ b/imagery/i.maxlik/i.maxlik.md @@ -0,0 +1,115 @@ +## DESCRIPTION + +*i.maxlik* is a maximum-likelihood discriminant analysis classifier. It +can be used to perform the second step in either an unsupervised or a +supervised image classification. + +Either image classification methods are performed in two steps. The +first step in an unsupervised image classification is performed by +*[i.cluster](i.cluster.md)*; the first step in a supervised +classification is executed by the GRASS program +*[g.gui.iclass](g.gui.iclass.md)* (or by providing any other raster map +with already existing training areas). In both cases, the second step in +the image classification procedure is performed by *i.maxlik*. + +In an unsupervised classification, the maximum-likelihood classifier +uses the cluster means and covariance matrices from the +*[i.cluster](i.cluster.md)* signature file to determine to which +category (spectral class) each cell in the image has the highest +probability of belonging. In a supervised image classification, the +maximum-likelihood classifier uses the region means and covariance +matrices from the spectral signature file generated by +*[g.gui.iclass](g.gui.iclass.md)*, based on regions (groups of image +pixels) chosen by the user, to determine to which category each cell in +the image has the highest probability of belonging. + +In either case, the raster map output by *i.maxlik* is a classified +image in which each cell has been assigned to a spectral class (i.e., a +category). The spectral classes (categories) can be related to specific +land cover types on the ground. + +## NOTES + +The maximum-likelihood classifier assumes that the spectral signatures +for each class (category) in each band file are normally distributed +(i.e., Gaussian in nature). Algorithms, such as +*[i.cluster](i.cluster.md)*, *[g.gui.iclass](g.gui.iclass.md)*, or +*[i.gensig](i.gensig.md)*, however, can create signatures that are not +valid distributed (more likely with *[g.gui.iclass](g.gui.iclass.md)).* +If this occurs, *i.maxlik* will reject them and display a warning +message. + +The signature file (**signaturefile**) contains the cluster and +covariance matrices that were calculated by the GRASS program +*[i.cluster](i.cluster.md)* (or the region means and covariance matrices +generated by *[g.gui.iclass](g.gui.iclass.md)*, if the user runs a +supervised classification). These spectral signatures are what determine +the categories (classes) to which image pixels will be assigned during +the classification process. + +The optional name of a **reject** raster map holds the reject threshold +results. This is the result of a chi square test on each discriminant +result at various threshold levels of confidence to determine at what +confidence level each cell classified (categorized). It is the reject +threshold map layer, and contains the index to one calculated confidence +level for each classified cell in the classified image. 16 confidence +intervals are predefined, and the reject map is to be interpreted as 1 = +keep and 16 = reject. One of the possible uses for this map layer is as +a mask, to identify cells in the classified image that have a low +probability (high reject index) of being assigned to the correct class. + +## EXAMPLE + +Second part of the unsupervised classification of a LANDSAT subscene +(VIZ, NIR, MIR channels) in North Carolina (see +*[i.cluster](i.cluster.md)* manual page for the first part of the +example): + +```bash +# using here the signaturefile created by i.cluster +i.maxlik group=lsat7_2002 subgroup=res_30m \ + signaturefile=cluster_lsat2002 \ + output=lsat7_2002_cluster_classes reject=lsat7_2002_cluster_reject + +# visually check result +d.mon wx0 +d.rast.leg lsat7_2002_cluster_classes +d.rast.leg lsat7_2002_cluster_reject + +# see how many pixels were rejected at given levels +r.report lsat7_2002_cluster_reject units=k,p + +# optionally, filter out pixels with high level of rejection +# here we remove pixels of at least 90% of rejection probability, i.e. categories 12-16 +r.mapcalc "lsat7_2002_cluster_classes_filtered = \ + if(lsat7_2002_cluster_reject <= 12, lsat7_2002_cluster_classes, null())" +``` + +![](i_maxlik_rgb.png) +RGB composite of input data + +![](i_maxlik_classes.png) +Output raster map with pixels classified (10 classes) + +![](i_maxlik_rejection.png) +Output raster map with rejection probability values (pixel +classification confidence levels) + +## SEE ALSO + +[Image processing](https://grasswiki.osgeo.org/wiki/Image_processing) +and [Image +classification](https://grasswiki.osgeo.org/wiki/Image_classification) +wiki pages and for historical reference also the GRASS GIS 4 *[Image +Processing +manual](https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf)* + +*[g.gui.iclass](g.gui.iclass.md), [i.cluster](i.cluster.md), +[i.gensig](i.gensig.md), [i.group](i.group.md), +[i.segment](i.segment.md), [i.smap](i.smap.md), [r.kappa](r.kappa.md)* + +## AUTHORS + +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory +Tao Wen, University of Illinois at Urbana-Champaign, Illinois +Semantic label support: Maris Nartiss, University of Latvia diff --git a/imagery/i.modis.qc/i.modis.qc.md b/imagery/i.modis.qc/i.modis.qc.md new file mode 100644 index 00000000000..7e5b2a76c24 --- /dev/null +++ b/imagery/i.modis.qc/i.modis.qc.md @@ -0,0 +1,501 @@ +## DESCRIPTION + +*i.modis.qc* extracts Requested Quality Assessment flags from the +following MODIS products: MOD09A1, MOD09Q1, MOD11A1, MOD11A2, MOD13A2, +MOD13Q1, MCD43B2. This does include MOD09A1 QA_state_500m layer (see +Notes). +Added MOD09GA support in 2016, it follows MOD09A1 and its StateQA, but +does not have BRDF State QA, instead has Salt Pan State QA. + +### MOD09A1 and MOD09Q1 + +```bash +MOD09A1/Q1: MODLAND QA Bits. bits=[0-1] +``` + +- \[00\]= class 0: Corrected product produced at ideal quality -- all + bands +- \[01\]= class 1: Corrected product produced at less than ideal quality + -- some or all bands +- \[10\]= class 2: Corrected product NOT produced due to cloud effect -- + all bands +- \[11\]= class 3: Corrected product NOT produced due to other reasons + -- some or all bands maybe be fill value (Note that a value of \[11\] + overrides a value of \[01\]) + +```bash +MOD09Q1: Cloud State. bits=[2-3] +``` + +- \[00\]= class 0: Clear -- No clouds +- \[01\]= class 1: Cloudy +- \[10\]= class 2: Mixed +- \[11\]= class 3: Not Set ; Assumed Clear + +```bash +MOD09Q1: Band-wise Data Quality 250m bits=[4-7][8-11] +MOD09A1: Band-wise Data Quality 500m bits=[2-5][6-9][10-13][14-17][18-21][22-25][26-29] +``` + +- \[0000\]= class 0: highest quality +- \[0111\]= class 1: noisy detector +- \[1000\]= class 2: dead detector; data interpolated in L1B +- \[1001\]= class 3: solar zenith ≥ 86 degrees +- \[1010\]= class 4: solar zenith ≥ 85 and \< 86 degrees +- \[1011\]= class 5: missing input +- \[1100\]= class 6: internal constant used in place of climatological + data for at least one atmospheric constant +- \[1101\]= class 7: correction out of bounds, pixel constrained to + extreme allowable value +- \[1110\]= class 8: L1B data faulty +- \[1111\]= class 9: not processed due to deep ocean or cloud +- Class 10-15: Combination of bits unused + +```bash +MOD09A1/Q1: Atmospheric correction bit=[12]/[30] +``` + +- \[0\]= class 0: Not Corrected product +- \[1\]= class 1: Corrected product + +```bash +MOD09A1/Q1: Adjacency correction bit=[13]/[31] +``` + +- \[0\]= class 0: Not Corrected product +- \[1\]= class 1: Corrected product + +```bash +MOD09Q1: Different orbit from 500m product, bit=[14] +``` + +- \[0\]= class 0: same orbit as 500m +- \[1\]= class 1: different orbit from 500m + +```bash +MOD09A1s: Cloud State bits=[0-1] +``` + +- \[00\]= class 0: clear +- \[01\]= class 1: cloudy +- \[10\]= class 2: mixed +- \[11\]= class 3: not set, assumed clear + +```bash +MOD09A1s: Cloud shadow bits=[2] +``` + +- \[0\]= class 0: no +- \[1\]= class 1: yes + +```bash +MOD09A1s: Land/Water Flag bits=[3-5] +``` + +- \[000\]= class 0: Shallow ocean +- \[001\]= class 1: Land +- \[010\]= class 2: Ocean coastlines and lake shorelines +- \[011\]= class 3: Shallow inland water +- \[100\]= class 4: Ephemeral water +- \[101\]= class 5: Deep inland water +- \[110\]= class 6: Continental/moderate ocean +- \[111\]= class 7: Deep ocean + +```bash +MOD09A1s: Aerosol Quantity bits=[6-7] +``` + +- \[00\]= class 0: Climatology +- \[01\]= class 1: Low +- \[10\]= class 2: Average +- \[11\]= class 3: High + +```bash +MOD09A1s: Cirrus detected bits=[8-9] +``` + +- \[00\]= class 0: None +- \[01\]= class 1: Small +- \[10\]= class 2: Average +- \[11\]= class 3: High + +```bash +MOD09A1s: Internal Cloud Algorithm Flag bits=[10] +``` + +- \[0\]= class 0: No cloud +- \[1\]= class 1: Cloud + +```bash +MOD09A1s: Internal Fire Algorithm Flag bits=[11] +``` + +- \[0\]= class 0: No fire +- \[1\]= class 1: Fire + +```bash +MOD09A1s: MOD35 snow/ice flag bits=[12] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +```bash +MOD09A1s: Pixel adjacent to cloud bits=[13] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +```bash +MOD09A1s: BRDF correction performed bits=[14] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +```bash +MOD09A1s: Internal Snow Mask bits=[15] +``` + +- \[0\]= class 0: No snow +- \[1\]= class 1: Snow + +### MOD11A1 + +```bash +MOD11A1: Mandatory QA Flags bits=[0-1] +``` + +- \[00\]= class 0: LST produced, good quality, not necessary to examine + more detailed QA +- \[01\]= class 1: LST produced, other quality, recommend examination of + more detailed QA +- \[10\]= class 2: LST not produced due to cloud effects +- \[11\]= class 3: LST not produced primarily due to reasons other than + cloud + +```bash +MOD11A1: Data Quality Flag bits=[2-3] +``` + +- \[00\]= class 0: Good data quality of L1B in bands 31 and 32 +- \[01\]= class 1: Other quality data +- \[10\]= class 2: TBD +- \[11\]= class 3: TBD + +```bash +MOD11A1: Emis Error Flag bits=[4-5] +``` + +- \[00\]= class 0: Average emissivity error ≤ 0.01 +- \[01\]= class 1: Average emissivity error ≤ 0.02 +- \[10\]= class 2: Average emissivity error ≤ 0.04 +- \[11\]= class 3: Average emissivity error \> 0.04 + +```bash +MOD11A1: LST Error Flag bits=[6-7] +``` + +- \[00\]= class 0: Average LST error ≤ 1 +- \[01\]= class 1: Average LST error ≤ 2 +- \[10\]= class 2: Average LST error ≤ 3 +- \[11\]= class 3: Average LST error \> 3 + +### MOD11A2 + +```bash +MOD11A2: Mandatory QA Flags bits=[0-1] +``` + +- \[00\]= class 0: LST produced, good quality, not necessary to examine + more detailed QA +- \[01\]= class 1: LST produced, other quality, recommend examination of + more detailed QA +- \[10\]= class 2: LST not produced due to cloud effects +- \[11\]= class 3: LST not produced primarily due to reasons other than + cloud + +```bash +MOD11A2: Data Quality Flag bits=[2-3] +``` + +- \[00\]= class 0: Good data quality of L1B in 7 TIR bands +- \[01\]= class 1: Other quality data +- \[10\]= class 2: TBD +- \[11\]= class 3: TBD + +```bash +MOD11A2: Emis Error Flag bits=[4-5] +``` + +- \[00\]= class 0: Average emissivity error ≤ 0.01 +- \[01\]= class 1: Average emissivity error ≤ 0.02 +- \[10\]= class 2: Average emissivity error ≤ 0.04 +- \[11\]= class 3: Average emissivity error \> 0.04 + +```bash +MOD11A2: LST Error Flag bits=[6-7] +``` + +- \[00\]= class 0: Average LST error ≤ 1 +- \[01\]= class 1: Average LST error ≤ 2 +- \[10\]= class 2: Average LST error ≤ 3 +- \[11\]= class 3: Average LST error \> 3 + +### MOD13A2 + +```bash +MOD13A2: Mandatory QA Flags 1km bits[0-1] +``` + +- \[00\]= class 0: VI produced, good quality +- \[01\]= class 1: VI produced, but check other QA +- \[10\]= class 2: Pixel produced, but most probably cloud +- \[11\]= class 3: Pixel not produced due to other reasons than clouds + +```bash +MOD13A2: VI Usefulness Flag bits[2-5] +``` + +- \[0000\]= class 0: Highest quality +- \[0001\]= class 1: Lower quality +- \[0010\]= class 2: Decreasing quality +- \[0100\]= class 3: Decreasing quality +- \[1000\]= class 4: Decreasing quality +- \[1001\]= class 5: Decreasing quality +- \[1010\]= class 6: Decreasing quality +- \[1100\]= class 7: Lowest quality +- \[1101\]= class 8: Quality so low that it is not useful +- \[1110\]= class 9: L1B data faulty +- \[1111\]= class 10: Not useful for any other reason/not processed + +```bash +MOD13A2: Aerosol quantity Flags 1km bits[6-7] +``` + +- \[00\]= class 0: Climatology +- \[01\]= class 1: Low +- \[10\]= class 2: Average +- \[11\]= class 3: High + +```bash +MOD13A2: Adjacent cloud detected 1km bit[8] +``` + +- \[00\]= class 0: No +- \[01\]= class 1: Yes + +```bash +MOD13A2: Atmosphere BRDF correction performed 1km bit[9] +``` + +- \[00\]= class 0: No +- \[01\]= class 1: Yes + +```bash +MOD13A2: Mixed clouds 1km bit[10] +``` + +- \[00\]= class 0: No +- \[01\]= class 1: Yes + +```bash +MOD13A2: Land/Water Flags 1km bits[11-13] +``` + +- \[000\]= class 0: Shallow Ocean +- \[001\]= class 1: Land (Nothing else but land) +- \[010\]= class 2: Ocean Coastlines and lake shorelines +- \[011\]= class 3: Shallow inland water +- \[100\]= class 4: Ephemeral water +- \[101\]= class 5: Deep inland water +- \[110\]= class 6: Moderate or continental ocean +- \[111\]= class 7: Deep ocean + +```bash +MOD13A2: Possible Snow/Ice 1km bits[14] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +```bash +MOD13A2: Possible Shadow 1km bits[15] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +### MOD13Q1 + +```bash +MOD13Q1: Mandatory QA Flags 250m bits[0-1] +``` + +- \[00\]= class 0: VI produced, good quality +- \[01\]= class 1: VI produced, but check other QA +- \[10\]= class 2: Pixel produced, but most probably cloud +- \[11\]= class 3: Pixel not produced due to other reasons than clouds + +```bash +MOD13Q1: VI Usefulness Flag 250m bits[2-5] +``` + +- \[0000\]= class 0: Highest quality +- \[0001\]= class 1: Lower quality +- \[0010\]= class 2: Decreasing quality +- \[0100\]= class 3: Decreasing quality +- \[1000\]= class 4: Decreasing quality +- \[1001\]= class 5: Decreasing quality +- \[1010\]= class 6: Decreasing quality +- \[1100\]= class 7: Lowest quality +- \[1101\]= class 8: Quality so low that it is not useful +- \[1110\]= class 9: L1B data faulty +- \[1111\]= class 10: Not useful for any other reason/not processed + +```bash +MOD13Q1: Aerosol quantity Flags 250m bits[6-7] +``` + +- \[00\]= class 0: Climatology +- \[01\]= class 1: Low +- \[10\]= class 2: Average +- \[11\]= class 3: High + +```bash +MOD13Q1: Adjacent cloud detected 250m bit[8] +``` + +- \[00\]= class 0: No +- \[01\]= class 1: Yes + +```bash +MOD13Q1: Atmosphere BRDF correction performed 250m bit[9] +``` + +- \[00\]= class 0: No +- \[01\]= class 1: Yes + +```bash +MOD13Q1: Mixed clouds 250m bit[10] +``` + +- \[00\]= class 0: No +- \[01\]= class 1: Yes + +```bash +MOD13Q1: Land/Water Flags 250m bits[11-13] +``` + +- \[000\]= class 0: Shallow Ocean +- \[001\]= class 1: Land (Nothing else but land) +- \[010\]= class 2: Ocean Coastlines and lake shorelines +- \[011\]= class 3: Shallow inland water +- \[100\]= class 4: Ephemeral water +- \[101\]= class 5: Deep inland water +- \[110\]= class 6: Moderate or continental ocean +- \[111\]= class 7: Deep ocean + +```bash +MOD13Q1: Possible Snow/Ice 250m bits[14] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +```bash +MOD13Q1: Possible Shadow 250m bits[15] +``` + +- \[0\]= class 0: No +- \[1\]= class 1: Yes + +### MCD43B2 + +```bash +MCD43B2: Albedo Quality Ancillary Platform Data 1km bits[0-3] +SDS: BRDF_Albedo_Ancillary +``` + +- \[0000\]= class 0: Satellite Platform: Terra +- \[0001\]= class 1: Satellite Platform: Terrra/Aqua +- \[0010\]= class 2: Satellite Platform: Aqua +- \[1111\]= class 15: Fill Value +- Classes 3-14: Not used + +```bash +MCD43B2: Albedo Quality Ancillary Land/Water Data 1km bits[4-7] +SDS: BRDF_Albedo_Ancillary +``` + +- \[0000\] class 0: Shallow Ocean +- \[0001\] class 1: Land (Nothing else but land) +- \[0010\] class 2: Ocean and lake shorelines +- \[0011\] class 3: Shallow inland water +- \[0100\] class 4: Ephemeral water +- \[0101\] class 5: Deep inland water +- \[0110\] class 6: Moderate or continental ocean +- \[0111\] class 7: Deep ocean +- \[1111\] class 15: Fill Value +- Classes 8-14: Not used + +```bash +MCD43B2: Albedo Quality Ancillary Sun Zenith Angle at Local Solar Noon Data 1km bits[8-14] +SDS: BRDF_Albedo_Ancillary +``` + +```bash +MCD43B2: Band-wise Albedo Quality Data 1km +SDS: BRDF_Albedo_Band_Quality +``` + +bits\[0-3\]\[4-7\]\[8-11\]\[12-15\]\[16-19\]\[20-23\]\[24-27\] + +- \[0000\]= class 0: best quality, 75% or more with best full inversions +- \[0001\]= class 1: good quality, 75% or more with full inversions +- \[0010\]= class 2: Mixed, 50% or less full inversions and 25% or less + fill values +- \[0011\]= class 3: All magnitude inversions or 50% or less fill values +- \[0100\]= class 4: 75% or more fill values +- Classes 5-14: Not Used +- \[1111\]= class 15: Fill Value + +## NOTES + +In MOD09A1: It seems that cloud related info is not filled properly in +the standard QC (MOD09A1 in this module) since version 3, State-QA 500m +images (MOD09A1s in this module) should be used (see Vermote et al., +2008). MOD11A2 quality control (QC) bands do not have a FillValue +(No-data) according to [MODIS Land Products +site](https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod11a2_v006). +However, the metadata of the QC bands (i.e.: `gdalinfo QC_band`) shows +`No-data=0`. This value is then transformed into GRASS NULLs when data +is imported through [r.in.gdal](r.in.gdal.md). Applying *i.modis.qc* on +those QC bands will not give the expected range of values in the +different QC bits. Therefore, before using *i.modis.qc*, the user needs +to set the NULL value in QC bands back to zero (i.e.: +`r.null map=QC_band null=0`) or just edit the metadata with GDAL +utilities before importing into GRASS GIS. This is a known issue for +MOD11A2 (8-day LST product), but other MODIS products might be affected +as well. + +## TODO + +Add more daily products. + +## REFERENCES + +- [MODIS + Products](https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table) +- Vermote E.F., Kotchenova S.Y., Ray J.P. MODIS Surface Reflectance + User's Guide. Version 1.2. June 2008. MODIS Land Surface Reflectance + Science Computing Facility. [Homepage](http://modis-sr.ltdri.org) + +## SEE ALSO + +*[i.vi](i.vi.md)* + +## AUTHOR + +Yann Chemin diff --git a/imagery/i.ortho.photo/i.ortho.camera/i.ortho.camera.md b/imagery/i.ortho.photo/i.ortho.camera/i.ortho.camera.md new file mode 100644 index 00000000000..e43bfad3379 --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.camera/i.ortho.camera.md @@ -0,0 +1,101 @@ +## DESCRIPTION + +*i.ortho.camera* creates or modifies entries in a camera reference file. +For ortho-photo rectification, a camera reference file is required for +computation of scanned image to photo-coordinate transformation +parameters. There are two coordinate systems: The image coordinate +system (in pixels) and the photo coordinate system (in milli-meters). +The inner orientation establishes a relation between the pixels and the +image coordinates with help of fiducial marks. + +The first prompt in the program will ask you for the name of the camera +reference file to be created or modified. You may create a new camera +reference file by entering a new name, or modify an existing camera +reference file by entering the name of an existing camera file. + +After entering the camera file name, following menu is displayed: + +Please provide the following information + +```bash + + CAMERA NAME: camera name______ + CAMERA IDENTIFICATION: identification___ + CALIBRATED FOCAL LENGTH mm.:_________________ + POINT OF SYMMETRY (X) mm.:_________________ + POINT OF SYMMETRY (Y) mm.:_________________ + MAXIMUM NUMBER OF FIDUCIALS:_________________ + + AFTER COMPLETING ALL ANSWERS, HIT TO CONTINUE + (OR TO CANCEL) +``` + +The camera name and identification describe the camera reference file. +The calibrated focal length and the point of symmetry are used in +computing the photo-to-target transformation parameters. These values +should be entered from the camera calibration report (usually available +from the photograph supplier). + +![Sketch of aerial photo](i_ortho_camera.png) +*This example is the camera Zeiss LMK9 265-002A belonging to the +Hellenic Military Geographical Survey (HMGS) and calibrated in December +1985* + +The photo coordinate system origin is the so-called calibrated principal +point (PP, Principal Point of Symmetry) which is in the center of the +image. The origin of the axes is at the intersection of the radii traced +from the fiducial marks. In the ideal case of no deviations in the +camera (see camera calibration certificate) the center is the origin and +the values are 0 for both X and Y of Point of Symmetry. But usually the +principal point does not fall on the intersection of the radii at the +center of the picture. This eccentricity is usually of the order of a +few micrometers. + +You are then asked to enter the X and Y photo coordinates of each +fiducial as follows. These fiducials (or reseau) marks are index marks +imaged on film which serve as reference photo coordinate system. The +maximum number of fiducials will determine the number of fiducial or +reseau coordinate pairs to be entered below. The origin is the center of +the image (or the point of symmetry) and X and Y are left-right and +up-down. The order is up to the user, but must be kept consistent +throughout the rectification process. + +On this screen you should enter the fiducial or reseau photo-coordinates +as given in the camera calibration report. The X, and Y coordinates are +in milli-meters from the principle point. + +Please provide the following information + +```bash + Fid# FID ID X Y + + 1__ _____ 0.0___ 0.0___ + 2__ _____ 0.0___ 0.0___ + 3__ _____ 0.0___ 0.0___ + 4__ _____ 0.0___ 0.0___ + 5__ _____ 0.0___ 0.0___ + 6__ _____ 0.0___ 0.0___ + 7__ _____ 0.0___ 0.0___ + 8__ _____ 0.0___ 0.0___ + 9__ _____ 0.0___ 0.0___ + 10_ _____ 0.0___ 0.0___ + + next: end__ + + AFTER COMPLETING ALL ANSWERS, HIT TO CONTINUE + (OR TO CANCEL) +``` + +The input display is repeated until the number of MAXIMUM FIDUCIALS is +reached. + +## SEE ALSO + +*[i.ortho.photo](i.ortho.photo.md), +[g.gui.photo2image](g.gui.photo2image.md), +[g.gui.image2target](g.gui.image2target.md), +[i.ortho.init](i.ortho.init.md)* + +## AUTHOR + +Mike Baba, DBA Systems, Inc. diff --git a/imagery/i.ortho.photo/i.ortho.elev/i.ortho.elev.md b/imagery/i.ortho.photo/i.ortho.elev/i.ortho.elev.md new file mode 100644 index 00000000000..feee58974bb --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.elev/i.ortho.elev.md @@ -0,0 +1,23 @@ +## DESCRIPTION + +*i.ortho.elev* is used to select or modify the target elevation model +for orthorectification of imagery. This elevation model is essential for +both the computation of photo-to-target parameters and for the actual +orthorectification of imagery group files. The elevation model selected +should cover the entire area of the image group to be orthorectified. +Optionally, scaled elevation data can be converted to real elevation +values specifying a mathematical expression. + +## SEE ALSO + +*[i.ortho.photo](i.ortho.photo.md) +[i.ortho.camera](i.ortho.camera.md) +[g.gui.photo2image](g.gui.photo2image.md) +[g.gui.image2target](g.gui.image2target.md) +[i.ortho.init](i.ortho.init.md) +[i.rectify](i.rectify.md)* + +## AUTHORS + +Mike Baba, DBA Systems, Inc. +Bugfixes and enhancements for GRASS GIS 7 by Markus Metz diff --git a/imagery/i.ortho.photo/i.ortho.init/i.ortho.init.md b/imagery/i.ortho.photo/i.ortho.init/i.ortho.init.md new file mode 100644 index 00000000000..c29e6cd56d8 --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.init/i.ortho.init.md @@ -0,0 +1,99 @@ +## DESCRIPTION + +Aerial photographs may be either vertical or oblique. Vertical +photographs can be truly vertical (nadir), or slightly tilted (less than +3 degree from the vertical). Usually aerial photos are tilted to some +degree. We refer to the term *vertical photograph* up to a tilt of 3 +degree. +Oblique aerial photographs are purposely taken with an angle between 3 +and 90 degree from the nadir direction. + +**The use of *i.ortho.init* (menu 6) is only required when rectifying a +tilted or oblique aerial photo.** + +*i.ortho.init* creates or modifies entries in a camera initial exposure +station file for imagery group referenced by a sub-block. These entries +include: the (XC,YC,ZC) standard (e.g. UTM) approximate coordinates of +the camera exposure station; initial roll, pitch, and yaw angles (in +degrees) of the cameras attitude; and the *a priori* standard deviations +for these parameters. During the imagery program, *i.photo.rectify*, the +initial camera exposure station file is used for computation of the +ortho-rectification parameters. If no initial camera exposure station +file exist, the default values are computed from the control points file +created in *[g.gui.image2target](g.gui.image2target.md)*. + +The following menu is displayed: + +```bash + Please provide the following information + + INITIAL XC: Meters __________ + INITIAL YC: Meters __________ + INITIAL ZC: Meters __________ + INITIAL omega (pitch) degrees: __________ + INITIAL phi (roll) degrees: __________ + INITIAL kappa (yaw) degrees: __________ + + Standard Deviation XC: Meters __________ + Standard Deviation YC: Meters __________ + Standard Deviation ZC: Meters __________ + Std. Dev. omega (pitch) degrees: __________ + Std. Dev. phi (roll) degrees: __________ + Std. Dev. kappa (yaw) degrees: __________ + + Use these values at run time? (1=yes, 0=no) + + AFTER COMPLETING ALL ANSWERS, HIT TO CONTINUE + (OR TO CANCEL) +``` + +The INITIAL values for (XC,YC,ZC) are expressed in standard (e.g. UTM) +coordinates, and represent an approximation for the location of the +camera at the time of exposure. + +- X: East aircraft position; +- Y: North aircraft position; +- Z: Flight altitude above sea level + +The INITIAL values for (omega,phi,kappa) are expressed in degrees, and +represent an approximation for the cameras attitude at the time of +exposure. + +- Omega (pitch): Raising or lowering of the aircraft's front (turning + around the wings' axis); +- Phi (roll): Raising or lowering of the wings (turning around the + aircraft's axis); +- Kappa (yaw): Rotation needed to align the aerial photo to true north: + needs to be denoted as +90 degree for clockwise turn and -90 degree + for a counterclockwise turn. + +If ground control points are available, the INITIAL values are +iteratively corrected. This is particularl useful when the INITIAL +values are rather rough estimates. + +The standard deviations for (XC,YC,ZC) are expressed in meters, and are +used as *a priori* values for the standard deviations used in +computation of the ortho rectification parameters. Higher values improve +the refinement of the initial camera exposure. As a rule of thumb, 5% of +the estimated target extents should be used. + +The standard deviations for (omega,phi,kappa) are expressed in degrees, +and are used as *a priori* values for the standard deviations used in +computation of the ortho rectification parameters. As a rule of thumb, 2 +degrees should be used. + +If *Use these values at run time? (1=yes, 0=no)* is set to 0, the values +in this menu are not used. + +## SEE ALSO + +*[i.ortho.photo](i.ortho.photo.md), +[g.gui.photo2image](g.gui.photo2image.md), +[g.gui.image2target](g.gui.image2target.md), +[i.ortho.elev](i.ortho.elev.md), [i.ortho.camera](i.ortho.camera.md), +[i.ortho.transform](i.ortho.transform.md), +[i.photo.rectify](i.photo.rectify.md)* + +## AUTHOR + +Mike Baba, DBA Systems, Inc. diff --git a/imagery/i.ortho.photo/i.ortho.photo/i.ortho.photo.md b/imagery/i.ortho.photo/i.ortho.photo/i.ortho.photo.md new file mode 100644 index 00000000000..019a39c5016 --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.photo/i.ortho.photo.md @@ -0,0 +1,328 @@ +## DESCRIPTION + +*i.ortho.photo* is a menu to launch the different parts of the ortho +rectification process of aerial imagery. *i.ortho.photo* allows the user +to ortho-rectify imagery group files consisting of several scanned +aerial photographs (raster maps) of a common area. *i.ortho.photo* +guides the user through 8 steps required to ortho-rectify the raster +maps in a single imagery group. Alternatively, all the steps can be +performed separately by running the appropriate modules. + +- *Initialization Options* + 1. Create/Modify imagery group to be orthorectified: + [i.group](i.group.md) + 2. Select/Modify target project (formerly known as location) and + mapset for orthorectification: [i.ortho.target](i.ortho.target.md) + 3. Select/Modify target elevation model used for orthorectification: + [i.ortho.elev](i.ortho.elev.md) + 4. Create/Modify camera file of imagery group: + [i.ortho.camera](i.ortho.camera.md) +- *Transformation Parameters Computation* + 1. Compute image-to-photo transformation: + [g.gui.photo2image](g.gui.photo2image.md) + 2. Initialize parameters of camera: [i.ortho.init](i.ortho.init.md) + 3. Compute ortho-rectification parameters from ground control points: + [g.gui.image2target](g.gui.image2target.md) +- *Ortho-rectification* + 1. Ortho-rectify imagery group: [i.ortho.rectify](i.ortho.rectify.md) + +The ortho-rectification procedure in GRASS GIS places the image pixels +on the surface of the earth by matching the coordinate system of the +aerial image in pixels (*image coordinate system*) and the coordinate +system of the camera sensor in millimetres (*photo coordinate system*) +for the interior orientation of the image, and further to the +georeferenced coordinate system defined by projection parametres +(*target coordinate system*) for exterior orientation. + +## EXAMPLE + +Five groups of input parameters are required for ortho-rectification: + +- Aerial image (images), +- Exposure and characteristics of the camera, i.e. its coordinates in + target coordinate system and height above sea level, focal length, + yaw, pitch and roll, dimensions of the camera sensor and resolution of + aerial images, +- Reference surface, i.e. digital elevation model in the target + coordinate system used to normalize the terrain undulation, +- Topographic reference map used to find corresponding ground control + points and/or, +- Coordinates of ground control points in the target coordinate system. + +
+ +[i.ortho.photo example](i_ortho_photo_step1.png) +*Example of an input oblique image in a source project* + +
+ +To ortho-rectify aerial images the user has to follow the menu options +step by step. Alternatively, all the steps can be performed separately +by running the corresponding modules. + +The aerial photos shall be stored in a **source project** - a general +Cartesian coordinate system (XY). Digital elevation model and a map +reference (topo sheet or other map used for ground control point +matching) shall be stored in a **target project** in a real-world +coordinate system (e.g. ETRS33). + +The steps to follow are described below: + +1. *Create/Modify imagery group to be orthorectified: + [i.group](i.group.md)* + + This step is to be run in the **source project**. + + In this first step an imagery group of aerial images for + ortho-rectification is created or modified. The current imagery + group is displayed at the top of the menu. You may select a new or + existing imagery group for the ortho-rectification. After choosing + this option you will be prompted for the name of a new or existing + imagery group. As a result, a new file + *mapset/group/name_of_group/**REF*** is created that contatins the + names of all images in a group. + + ```bash + IMG_0020 source_mapset + IMG_0021 source_mapset + IMG_0022 source_mapset + ``` + +2. *Select/Modify target project and mapset for orthorectification: + [i.ortho.target](i.ortho.target.md)* + + This step is to be run in the **source project**. + + The target project and mapset may be selected or modified in Step 2. + You will be prompted for the names of the projected target project + and mapset where the ortho-rectified raster maps will reside. The + target project is also the project from which the elevation model + (raster map) will be selected (see Step 3). In Step 2, a new file + *mapset/group/name_of_group/**TARGET*** is created contatining the + names of target project and mapset. + + ```bash + ETRS_33N + target_mapset + ``` + +3. *Select/Modify target elevation model used for orthorectification: + [i.ortho.elev](i.ortho.elev.md)* + + This step is to be run in the **source project**. + + Step 3 allows you to select the raster map from the target project + to be used as the elevation model. The elevation model is required + for both the computation of photo-to-target parameters (Step 6) and + for the ortho-rectification of the imagery group files (Step 8). The + raster map selected for the elevation model should cover the entire + area of the image group to be ortho-rectified. DTED and DEM files + are suitable for use as elevation model in the ortho-rectification + program. In Step 3 you will be prompted for the name of the raster + map in the target project that you want to use as the elevation + model. As a result of this step, a new file + *mapset/group/name_of_group/**ELEVATION*** is created contatining + the name and mapset of the chosen DEM. + + ```bash + elevation layer :ELEVATION + mapset elevation:target_mapset + location :ETRS_33N + math expression :(null) + units :(null) + no data values :(null) + ``` + +4. *Create/Modify camera file of imagery group: + [i.ortho.camera](i.ortho.camera.md)* + + This step is to be run in the **source project**. + + In Step 4 you may select or create a camera reference file that will + be used with the current imagery group. A camera reference file + contains information on the internal characteristics of the aerial + camera, as well as the geometry of the fiducial or reseau marks. The + most important characteristic of the camera is its focal length. + Fiducial or reseau marks locations are required to compute the + scanned image to photo coordinate transformation parameter (Step 5). + Two new files are created in this step: a file + *mapset/group/name_of_group/**CAMERA***, contatining the name of the + reference camera and a file *mapset/camera/**name_of_reference***, + contatining the camera parameters. + + ```bash + CAMERA NAME sony + CAMERA ID 123 + CAMERA XP 0 + CAMERA YP 0 + CAMERA CFL 16 + NUM FID 4 + 0 -11.6 0 + 1 0 7.7 + 2 11.6 0 + 3 0 -7.7 + ``` + +5. *Compute image-to-photo transformation: + [g.gui.photo2image](g.gui.photo2image.md)* + + This step is to be run in the **source project**. + + The scanned image to photo coordinate transformation parameters, + i.e. the "interior orientation", is computed in Step 5. In this + interactive step you associate the scanned reference points + (fiducials, reseau marks, etc.) with their known photo coordinates + from the camera reference file. A new file + *mapset/group/name_of_group/**REF_POINTS*** is created, contatining + a list of pairs of coordinates in image and photo coordinate + systems. + + ```bash + # Ground Control Points File + # + # target location: XY + # target mapset: source_mapset + # source target status + # east north east north (1=ok, 0=ignore) + #------------------------------------------------------------- + 0 1816 -11.6 0.0 1 + 2728 3632 0.0 7.7 1 + 5456 1816 11.6 0.0 1 + 2728 0.0 0.0 -7.7 1 + ``` + +
+ + [i.ortho.photo example](i_ortho_photo_step5.png) + *Step 5: Image-to-photo transformation of an oblique image* + +
+ +6. *Initialize parameters of camera: [i.ortho.init](i.ortho.init.md)* + + This step is to be run in the **source project**. + + In Step 6, initial camera exposure station parameters and initial + variances may be selected or modified. + + - **X**: East aircraft position; + - **Y**: North aircraft position; + - **Z**: Flight height above surface; + - **Omega (pitch)**: Raising or lowering of the aircraft's front + (turning around the wings' axis); + - **Phi (roll)**: Raising or lowering of the wings (turning around + the aircraft's axis); + - **Kappa (yaw)**: Rotation needed to align the aerial photo to true + north: needs to be denoted as +90° for clockwise turn and -90° for + a counter-clockwise turn. + +
+ + [i.ortho.photo example](i_ortho_photo_step6.png) + *Principle of pitch and yaw* + +
+ + In Step 6, a new file *mapset/group/name_of_group/**INIT_EXP*** is + created, contatining camera parameters. + + ```bash + INITIAL XC 215258.345387 + INITIAL YC 6911444.022270 + INITIAL ZC 1101.991120 + INITIAL OMEGA 0.000000 + INITIAL PHI -0.168721 + INITIAL KAPPA 3.403392 + VARIANCE XC 5.000000 + VARIANCE YC 5.000000 + VARIANCE ZC 5.000000 + VARIANCE OMEGA 0.000000 + VARIANCE PHI 0.020153 + VARIANCE KAPPA 0.017453 + STATUS (1=OK, 0=NOT OK) 0 + ``` + +7. *Compute ortho-rectification parameters from ground control points: + [g.gui.image2target](g.gui.image2target.md)* + + This step is to be run in the **target project**. + + The photo to target transformation parameters, i.e. the "exterior + orientation", is computed in Step 7. In this interactive step, + control points are marked on one or more imagery group files and + associated with the known standard (e.g. UTM) and elevation + coordinates. Reasonable rectification results can be obtained with + around twelve control points well distributed over the image. In + this step, a new file + *mapset/group/name_of_group/**CONTROL_POINTS*** is created, + containing a list of pairs of coordinates of ground control points + in photo and target coordinate systems. + + ```bash + # Ground Control Points File + # + # target location: ETRS_33N + # target mapset: target_mapset + # source target status + # east north height east north height (1=ok, 0=ignore) + #------------------------------ ---------------------- --------------- + 98.3679932698 906.327649515 0.0 1.0 5.0 100.0 1 + 733.293023813 1329.61100321 0.0 2.0 6.0 100.0 1 + 1292.6317412 1703.76325335 0.0 3.0 7.0 100.0 1 + 1625.54617472 1368.11694482 0.0 4.0 6.0 100.3 1 + 3239.82849913 1390.97403968 0.0 7.4 6.0 100.3 1 + 1570.09788497 2790.06537829 0.0 3.0 11.0 100.0 1 + ``` + +
+ + [i.ortho.photo example](i_ortho_photo_step7.png) + *Step 7: Detail of ground control points matching in an oblique + image and terrain model* + +
+ +8. *Ortho-rectify imagery group: [i.ortho.rectify](i.ortho.rectify.md)* + + This step is to be run in the **source project**. + + Step 8 is used to perform the actual image ortho-rectification after + all of the transformation parameters have been computed. + Ortho-rectified raster files will be created in the target project + for each selected imagery group file. You may select either the + current window in the target project or the minimal bounding window + for the ortho-rectified image. + +
+ + [i.ortho.photo example](i_ortho_photo_step8.png) + *Step 8: Ortho-rectified oblique image* + +
+ + As a result, the ortho-rectified raster map is available for + visualization and further image analysis. + +## REFERENCES + +Wolf P.R. (1983). *Elements of Photogrammetry: With Air Photo +Interpretation and Remote Sensing* **McGraw Hill Higher Education** +ISBN-10: 0070713456, ISBN-13: 978-0070713451 + +## SEE ALSO + +*[g.gui.image2target](g.gui.image2target.md), +[g.gui.photo2image](g.gui.photo2image.md), [i.group](i.group.md), +[i.ortho.camera](i.ortho.camera.md), [i.ortho.elev](i.ortho.elev.md), +[i.ortho.init](i.ortho.init.md), [i.ortho.rectify](i.ortho.rectify.md), +[i.ortho.target](i.ortho.target.md)* + +## AUTHORS + +Mike Baba, DBA Systems, Inc. +GRASS development team, 199?-2017 diff --git a/imagery/i.ortho.photo/i.ortho.rectify/i.ortho.rectify.md b/imagery/i.ortho.photo/i.ortho.rectify/i.ortho.rectify.md new file mode 100644 index 00000000000..4342a8829f2 --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.rectify/i.ortho.rectify.md @@ -0,0 +1,110 @@ +## DESCRIPTION + +*i.photo.rectify* rectifies an image by using the image to photo +coordinate transformation matrix created by +[g.gui.photo2image](g.gui.photo2image.md) and the rectification +parameters created by [g.gui.image2target](g.gui.image2target.md). +Rectification is the process by which the geometry of an image is made +planimetric. This is accomplished by mapping an image from one +coordinate system to another. In *i.photo.rectify* the parameters +computed by [g.gui.photo2image](g.gui.photo2image.md) and +[g.gui.image2target](g.gui.image2target.md) are used in equations to +convert x,y image coordinates to standard map coordinates for each pixel +in the image. The result is an image with a standard map coordinate +system, compensated for relief distortions and photographic tilt. Upon +completion of the program the rectified image is deposited in a +previously targeted GRASS project (location). + +Images can be resampled with various different interpolation methods: +nearest neighbor assignment, bilinear and bicubic interpolation. The +bilinear and bicubic interpolation methods are also available with a +fallback option. These methods "fall back" to simpler interpolation +methods along NULL borders. That is, from bicubic to bilinear to +nearest. + +The process may take an hour or more depending on the size of the image, +the speed of the computer, the number files, and the size and resolution +of the selected window. + +The rectified image will be located in the target project when the +program is completed. The original unrectified files are not modified or +removed. + +The optional *angle* output holds the camera angle in degrees to the +local surface, considering local slope and aspect. A value of 90 degrees +indicates that the camera angle was orthogonal to the local surface, a +value of 0 degrees indicates that the camera angle was parallel to the +local surface and negative values indicate that the surface was +invisible to the camera. As a rule of thumb, values below 30 degrees +indicate problem areas where the orthorectified output will appear +blurred. Because terrain shadowing effects are not considered, areas +with high camera angles may also appear blurred if they are located +(viewed from the camera position) behind mountain ridges or peaks. + +*i.photo.rectify* can be run directly, specifying options in the command +line or the GUI, or it can be invoked as OPTION 8 through +[i.ortho.photo](i.ortho.photo.md). If invoked though +[i.ortho.photo](i.ortho.photo.md), an interactive terminal is used to +determine the options. + +#### Interactive mode + +You are first asked if all images within the imagery group should be +rectified. If this option is not chosen, you are asked to specify for +each image within the imagery group whether it should be rectified or +not. + +More than one file may be rectified at a time. Each file should have a +unique output file name. The next prompt asks you for an extension to be +appended to the rectified images. + +The next prompt will ask you whether a camera angle map should be +produced and if yes, what should be its name. + +After that you are asked if overwriting existing maps in the target +project and mapset should be allowed. + +The next prompt asks you to select one of two windows: + +```bash + Please select one of the following options + 1. Use the current window in the target project + 2. Determine the smallest window which covers the image + > +``` + +If you choose option 2, you can also specify a desired target +resolution. + +*i.photo.rectify* will only rectify that portion of the image that +occurs within the chosen window. Only that portion will be relocated in +the target database. It is therefore important to check the current +window in the target project if choice number one is selected. + +Next you are asked to select an interpolation method. + +```bash + Please select one of the following interpolation methods + 1. nearest neighbor + 2. bilinear + 3. bicubic + 4. bilinear with fallback + 5. bicubic with fallback + > +``` + +The last prompt will ask you about the amount of memory to be used by +*i.photo.rectify*. + +## SEE ALSO + +*[i.ortho.photo](i.ortho.photo.md), [i.ortho.camera](i.ortho.camera.md), +[g.gui.photo2image](g.gui.photo2image.md), +[g.gui.image2target](g.gui.image2target.md), +[i.ortho.init](i.ortho.init.md), [i.rectify](i.rectify.md)* + +## AUTHORS + +Mike Baba, DBA Systems, Inc. +Updated rectification and elevation map to FP 1/2002 Markus Neteler +Bugfixes and enhancements 12/2010 Markus Metz diff --git a/imagery/i.ortho.photo/i.ortho.target/i.ortho.target.md b/imagery/i.ortho.photo/i.ortho.target/i.ortho.target.md new file mode 100644 index 00000000000..743e0edd587 --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.target/i.ortho.target.md @@ -0,0 +1,17 @@ +## DESCRIPTION + +*i.ortho.target* sets the image group target project (location) and +mapset. + +## SEE ALSO + +*[i.ortho.photo](i.ortho.photo.md), [i.ortho.elev](i.ortho.elev.md), +[i.ortho.camera](i.ortho.camera.md), +[g.gui.photo2image](g.gui.photo2image.md), +[g.gui.image2target](g.gui.image2target.md), +[i.ortho.init](i.ortho.init.md), [i.ortho.rectify](i.ortho.rectify.md)* + +## AUTHOR + +Mike Baba, DBA Systems, Inc. +GRASS development team, 2017 diff --git a/imagery/i.ortho.photo/i.ortho.transform/i.ortho.transform.md b/imagery/i.ortho.photo/i.ortho.transform/i.ortho.transform.md new file mode 100644 index 00000000000..36ab9c8026a --- /dev/null +++ b/imagery/i.ortho.photo/i.ortho.transform/i.ortho.transform.md @@ -0,0 +1,35 @@ +## DESCRIPTION + +*i.ortho.transform* is an utility to compute transformation based upon +GCPs and output error measurements. + +If coordinates are given with the **input** file option or fed from +`stdin`, both the input and the output format is "x y z" with one +coordinate pair per line. Reverse transform is performed with the **-r** +flag. + +The **format** option determines how control points are printed out. A +summary on the control points can be printed with the **-s** flag. The +summary includes maximum deviation observed when transforming GCPs and +overall RMS. The **format** option is ignored when coordinates are given +with the **input** file option. + +## NOTES + +Ortho-transformation is a 2-step transformation. First, source +coordinates are transformed to sensor coordinates, then sensor +coordinates are transformed to target coordinates. + +## SEE ALSO + +*[i.rectify](i.rectify.md)* + +## TODO + +Update this document with x,y,z\<-\>E,N,H information + +## AUTHORS + +Brian J. Buckley +Glynn Clements +Hamish Bowman diff --git a/imagery/i.pca/i.pca.md b/imagery/i.pca/i.pca.md new file mode 100644 index 00000000000..8d47db52d9d --- /dev/null +++ b/imagery/i.pca/i.pca.md @@ -0,0 +1,102 @@ +## DESCRIPTION + +*i.pca* is an image processing program based on the algorithm provided +by Vali (1990), that processes n (n \>= 2) input raster map layers and +produces n output raster map layers containing the principal components +of the input data in decreasing order of variance ("contrast"). The +output raster map layers are assigned names with .1, .2, ... .n +suffixes. The numbers used as suffix correspond to percent importance +with .1 being the scores of the principal component with the highest +importance. + +The current geographic region definition and raster mask settings are +respected when reading the input raster map layers. When the rescale +option is used, the output files are rescaled to fit the min,max range. + +The order of the input bands does not matter for the output maps (PC +scores), but does matter for the vectors (loadings), since each loading +refers to a specific input band. + +If the output is not rescaled (*rescale=0,0*, the output raster maps +will be of type DCELL, otherwise the output raster maps will be of type +CELL. + +By default, the values of the input raster maps are centered for each +map separately with *x - mean*. With *-n*, the input raster maps are +normalized for each map separately with *(x - mean) / stddev*. +Normalizing is highly recommended when the input raster maps have +different units, e.g. represent different environmental parameters. + +The *-f* flag, together with the *percent* option, can be used to remove +noise from input bands. Input bands will be recalculated from a subset +of the principal components (inverse PCA). The subset is selected by +using only the most important (highest eigenvalue) principal components +which explain together *percent* percent variance observed in the input +bands. + +## NOTES + +Richards (1986) gives a good example of the application of principal +components analysis (PCA) to a time series of LANDSAT images of a burned +region in Australia. + +Eigenvalue and eigenvector information is stored in the output maps' +history files. View with *r.info*. + +## EXAMPLE + +PCA calculation using Landsat7 imagery in the North Carolina sample +dataset: + +```bash +g.region raster=lsat7_2002_10 -p +i.pca in=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 \ + out=lsat7_2002_pca + +r.info -h lsat7_2002_pca.1 + Eigen values, (vectors), and [percent importance]: + PC1 4334.35 ( 0.2824, 0.3342, 0.5092,-0.0087, 0.5264, 0.5217) [83.04%] + PC2 588.31 ( 0.2541, 0.1885, 0.2923,-0.7428,-0.5110,-0.0403) [11.27%] + PC3 239.22 ( 0.3801, 0.3819, 0.2681, 0.6238,-0.4000,-0.2980) [ 4.58%] + PC4 32.85 ( 0.1752,-0.0191,-0.4053, 0.1593,-0.4435, 0.7632) [ 0.63%] + PC5 20.73 (-0.6170,-0.2514, 0.6059, 0.1734,-0.3235, 0.2330) [ 0.40%] + PC6 4.08 (-0.5475, 0.8021,-0.2282,-0.0607,-0.0208, 0.0252) [ 0.08%] + +d.mon wx0 +d.rast lsat7_2002_pca.1 +# ... +d.rast lsat7_2002_pca.6 +``` + +In this example, the first two PCAs (PCA1 and PCA2) already explain +94.31% of the variance in the six input channels. + +![PCA result](i_pca_result.png) +Resulting PCA maps calculated from the Landsat7 imagery (NC, USA) + +## SEE ALSO + +Richards, John A., **Remote Sensing Digital Image Analysis**, +Springer-Verlag, 1986. + +Vali, Ali R., Personal communication, Space Research Center, University +of Texas, Austin, 1990. + +*[i.cca](i.cca.md), [g.gui.iclass](g.gui.iclass.md), [i.fft](i.fft.md), +[i.ifft](i.ifft.md), [m.eigensystem](m.eigensystem.md), +[r.covar](r.covar.md), [r.mapcalc](r.mapcalc.md)* + +*[Principal Components Analysis +article](https://grasswiki.osgeo.org/wiki/Principal_Components_Analysis) +(GRASS Wiki)* + +## AUTHORS + +David Satnik, GIS Laboratory + +Major modifications for GRASS 4.1 were made by +Olga Waupotitsch and Michael Shapiro, U.S.Army Construction Engineering +Research Laboratory + +Rewritten for GRASS 6.x and major modifications by +Brad Douglas diff --git a/imagery/i.rectify/i.rectify.md b/imagery/i.rectify/i.rectify.md new file mode 100644 index 00000000000..32fbbf6395f --- /dev/null +++ b/imagery/i.rectify/i.rectify.md @@ -0,0 +1,169 @@ +## DESCRIPTION + +*i.rectify* uses the control points included in the source data or +identified with the [Ground Control Points Manager](wxGUI.gcp.md) to +calculate a transformation matrix and then converts x,y cell coordinates +to standard map coordinates for each pixel in the image. The result is a +planimetric image with a transformed coordinate system (i.e., a +different coordinate system than before it was rectified). Supported +transformation methods are first, second, and third order polynomial and +thin plate spline. Thin plate spline is recommended for ungeoreferenced +satellite imagery where ground control points (GCPs) are included. +Examples are +[NOAA/AVHRR](https://gdal.org/en/stable/drivers/raster/l1b.html) and +[ENVISAT](https://gdal.org/en/stable/drivers/raster/esat.html#raster-esat) +imagery which include throusands of GCPs. + +If no ground control points are available, the [Ground Control Points +Manager](wxGUI.gcp.md) must be run before *i.rectify*. An image must be +georeferenced before it can reside in a standard coordinate project, and +therefore be analyzed with the other map layers there. Upon completion +of *i.rectify*, the rectified image is deposited in the target standard +coordinate project. This project is selected using +*[i.target](i.target.md)*. + +More than one raster map may be rectified at a time. Each cell file +should be given a unique output file name. The rectified image or +rectified raster maps will be located in the target project when the +program is completed. The original unrectified files are not modified or +removed. + +If the **-c** flag is used, *i.rectify* will only rectify that portion +of the image or raster map that occurs within the chosen window region +in the target project, and only that portion of the cell file will be +relocated in the target database. It is important therefore, to check +the current mapset window in the target project if the **-c** flag is +used. + +If you are rectifying a file with plans to patch it to another file +using the GRASS program *r.patch*, choose option number one, the current +window in the target project. This window, however, must be the default +window for the target project. When a file being rectified is smaller +than the default window in which it is being rectified, NULLs are added +to the rectified file. Patching files of the same size that contain NULL +data, eliminates the possibility of a no-data line in the patched +result. This is because, when the images are patched, the NULLs in the +image are "covered" with non-NULL pixel values. When rectifying files +that are going to be patched, rectify all of the files using the same +default window. + +### Coordinate transformation + +The desired order of transformation (1, 2, or 3) is selected with the +**order** option. The program will calculate the RMSE and check the +required number of points. + +#### Linear affine transformation (1st order transformation) + +x' = ax + by + c + +y' = Ax + By + C + +The a, b, c, A, B, C are determined by least squares regression based on +the control points entered. This transformation applies scaling, +translation and rotation. It is NOT a general purpose rubber-sheeting +like TPS, nor is it ortho-photo rectification using a DEM, not second +order polynomial, etc. It can be used if (1) you have geometrically +correct images, and (2) the terrain or camera distortion effect can be +ignored. + +#### Polynomial Transformation Matrix (2nd, 3d order transformation) + +*i.rectify* uses a first, second, or third order transformation matrix +to calculate the registration coefficients. The number of control points +required for a selected order of transformation (represented by n) is + +((n + 1) \* (n + 2) / 2) + +or 3, 6, and 10 respectively. It is strongly recommended that one or +more additional points be identified to allow for an overly-determined +transformation calculation which will generate the Root Mean Square +(RMS) error values for each included point. The RMS error values for all +the included control points are immediately recalculated when the user +selects a different transformation order from the menu bar. The +polynomial equations are performed using a modified Gaussian elimination +method. + +#### Thin plate spline (TPS) transformation + +TPS transformation is selected with the **-t** flag. This method of +coordinate transformation is recommended for satellite imagery where +hundreds or thousands of GCPs are included, and for historical printed +or scanned maps with unknown georeferencing and/or known localized +distortions. + +TPS combines a linear affine transformation with individual +transformation coefficients for each GCP, using the radial basis kernel +function with the distance *dist* between any two points: + +dist2 \* log(dist) + +As a consequence, localized distortions can be removed with TPS +transformation. For example, scan line sensors will have due to the +changing viewing angle larger distortions towards the end points of the +scan line than at the center of the scan line. Even higher order +polynomial transformations are not able to remove these locally +different distortions, but TPS transformation can. For best results, TPS +requires an even and, for localized distortions, dense spacing of GCPs. + +### Resampling method + +The rectified data is resampled with one of seven different methods: +*nearest*, *bilinear*, *cubic*, *lanczos*, *bilinear_f*, *cubic_f*, or +*lanczos_f*. + +The *method=nearest* method, which performs a nearest neighbor +assignment, is the fastest of the resampling methods. It is primarily +used for categorical data such as a land use classification, since it +will not change the values of the data cells. The *method=bilinear* +method determines the new value of the cell based on a weighted distance +average of the 4 surrounding cells in the input map. The *method=cubic* +method determines the new value of the cell based on a weighted distance +average of the 16 surrounding cells in the input map. The +*method=lanczos* method determines the new value of the cell based on a +weighted distance average of the 25 surrounding cells in the input map. + +The bilinear, cubic and lanczos interpolation methods are most +appropriate for continuous data and cause some smoothing. These options +should not be used with categorical data, since the cell values will be +altered. + +In the bilinear, cubic and lanczos methods, if any of the surrounding +cells used to interpolate the new cell value are NULL, the resulting +cell will be NULL, even if the nearest cell is not NULL. This will cause +some thinning along NULL borders, such as the coasts of land areas in a +DEM. The *bilinear_f*, *cubic_f* and *lanczos_f* interpolation methods +can be used if thinning along NULL edges is not desired. These methods +"fall back" to simpler interpolation methods along NULL borders. That +is, from lanczos to cubic to bilinear to nearest. + +If nearest neighbor assignment is used, the output map has the same +raster format as the input map. If any of the other interpolations is +used, the output map is written as floating point. + +## NOTES + +If *i.rectify* starts normally but after some time the following text is +seen: +` ERROR: Error writing segment file ` +the user may try the **-c** flag or the module needs more free space on +the hard drive. + +## SEE ALSO + +The GRASS 4 *[Image Processing +manual](https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf)* + +*[m.transform](m.transform.md), [r.proj](r.proj.md), +[v.proj](v.proj.md), [i.group](i.group.md), [i.target](i.target.md)* +*[Ground Control Points Manager](wxGUI.gcp.md)* + +## AUTHORS + +William R. Enslin, Michigan State University, Center for Remote Sensing + +Modified for GRASS 5.0 by: +Luca Palmeri () +Bill Hughes +Pierre de Mouveaux () +CMD mode by Bob Covill diff --git a/imagery/i.rgb.his/i.rgb.his.md b/imagery/i.rgb.his/i.rgb.his.md new file mode 100644 index 00000000000..7e5f386fd82 --- /dev/null +++ b/imagery/i.rgb.his/i.rgb.his.md @@ -0,0 +1,20 @@ +## DESCRIPTION + +*i.rgb.his* is an image processing program that processes three input +raster map layers as red, green, and blue components and produces three +output raster map layers representing the hue, intensity, and saturation +of the data. The output raster map layers are created by a standard +red-green-blue (RGB) to hue-intensity-saturation (HIS) color +transformation. Each output raster map layer is given a linear gray +scale color table. The current geographic region definition and mask +settings are respected. + +## SEE ALSO + +*[i.his.rgb](i.his.rgb.md)* + +## AUTHOR + +David Satnik, GIS Laboratory, Central Washington University, +with acknowledgements to Ali Vali, Space Research Center, for the core +routine. diff --git a/imagery/i.segment/i.segment.md b/imagery/i.segment/i.segment.md new file mode 100644 index 00000000000..8e9d6616a5f --- /dev/null +++ b/imagery/i.segment/i.segment.md @@ -0,0 +1,272 @@ +## DESCRIPTION + +*i.segment* identifies segments (objects) from imagery data. + +Image segmentation or object recognition is the process of grouping +similar pixels into unique segments, also referred to as objects. +Boundary and region based algorithms are described in the literature, +currently a region growing and merging algorithm is implemented. Each +object found during the segmentation process is given a unique ID and is +a collection of contiguous pixels meeting some criteria. Note the +contrast with image classification where all pixels similar to each +other are assigned to the same class and do not need to be contiguous. +The image segmentation results can be useful on their own, or used as a +preprocessing step for image classification. The segmentation +preprocessing step can reduce noise and speed up the classification. + +## NOTES + +### Region Growing and Merging + +This segmentation algorithm sequentially examines all current segments +in the raster map. The similarity between the current segment and each +of its neighbors is calculated according to the given distance formula. +Segments will be merged if they meet a number of criteria, including: + +1. The pair is mutually most similar to each other (the similarity + distance will be smaller than to any other neighbor), and +2. The similarity must be lower than the input threshold. The process + is repeated until no merges are made during a complete pass. + +#### Similarity and Threshold + +The similarity between segments and unmerged objects is used to +determine which objects are merged. Smaller distance values indicate a +closer match, with a similarity score of zero for identical pixels. + +During normal processing, merges are only allowed when the similarity +between two segments is lower than the given threshold value. During the +final pass, however, if a minimum segment size of 2 or larger is given +with the **minsize** parameter, segments with a smaller pixel count will +be merged with their most similar neighbor even if the similarity is +greater than the threshold. + +The **threshold** must be larger than 0.0 and smaller than 1.0. A +threshold of 0 would allow only identical valued pixels to be merged, +while a threshold of 1 would allow everything to be merged. The +threshold is scaled to the data range of the entire input data, not the +current computational region. This allows the application of the same +threshold to different computational regions when working on the same +dataset, ensuring that this threshold has the same meaning in all +subregions. + +Initial empirical tests indicate threshold values of 0.01 to 0.05 are +reasonable values to start. It is recommended to start with a low value, +e.g. 0.01, and then perform hierarchical segmentation by using the +output of the last run as **seeds** for the next run. + +#### Calculation Formulas + +Both Euclidean and Manhattan distances use the normal definition, +considering each raster in the image group as a dimension. In future, +the distance calculation will also take into account the shape +characteristics of the segments. The normal distances are then +multiplied by the input radiometric weight. Next an additional +contribution is added: +`(1-radioweight) * {smoothness * smoothness weight + compactness * (1-smoothness weight)}`, +where `compactness = Perimeter Length / sqrt( Area )` and +`smoothness = Perimeter Length / Bounding Box`. The perimeter length is +estimated as the number of pixel sides the segment has. + +#### Seeds + +The seeds map can be used to provide either seed pixels (random or +selected points from which to start the segmentation process) or seed +segments. If the seeds are the results of a previous segmentation with +lower threshold, hierarchical segmentation can be performed. The +different approaches are automatically detected by the program: any +pixels that have identical seed values and are contiguous will be +assigned a unique segment ID. + +#### Maximum number of segments + +The current limit with CELL storage used for segment IDs is 2 billion +starting segment IDs. Segment IDs are assigned whenever a yet +unprocessed pixel is merged with another segment. Integer overflow can +happen for computational regions with more than 2 billion cells and very +low threshold values, resulting in many segments. If integer overflow +occurs durin region growing, starting segments can be used (created by +initial classification or other methods). + +#### Goodness of Fit + +The **goodness** of fit for each pixel is calculated as 1 - distance of +the pixel to the object it belongs to. The distance is calculated with +the selected **similarity** method. A value of 1 means identical values, +perfect fit, and a value of 0 means maximum possible distance, worst +possible fit. + +### Mean shift + +Mean shift image segmentation consists of 2 steps: anisotrophic +filtering and 2. clustering. For anisotrophic filtering new cell values +are calculated from all pixels not farther than **radius** pixels away +from the current pixel and with a spectral difference not larger than +**hr**. That means that pixels that are too different from the current +pixel are not considered in the calculation of new pixel values. +**radius** and **hr** are the spatial and spectral (range) bandwidths +for anisotrophic filtering. Cell values are iteratively recalculated +(shifted to the segment's mean) until the maximum number of iterations +is reached or until the largest shift is smaller than **threshold**. + +If input bands have been reprojected, they should not be reprojected +with bilinear resampling because that method causes smooth transitions +between objects. More appropriate methods are bicubic or lanczos +resampling. + +### Boundary Constraints + +Boundary constraints limit the adjacency of pixels and segments. Each +unique value present in the **bounds** raster are considered as a mask. +Thus, no segments in the final segmented map will cross a boundary, even +if their spectral data is very similar. + +### Minimum Segment Size + +To reduce the salt and pepper effect, a **minsize** greater than 1 will +add one additional pass to the processing. During the final pass, the +threshold is ignored for any segments smaller then the set size, thus +forcing very small segments to merge with their most similar neighbor. A +minimum segment size larger than 1 is recommended when using adaptive +bandwidth selected with the **-a** flag. + +## EXAMPLES + +### Segmentation of RGB orthophoto + +This example uses the ortho photograph included in the NC Sample +Dataset. Set up an imagery group: + +```bash +i.group group=ortho_group input=ortho_2001_t792_1m@PERMANENT +``` + +Set the region to a smaller test region (resolution taken from input +ortho photograph). + +```bash +g.region -p raster=ortho_2001_t792_1m n=220446 s=220075 e=639151 w=638592 +``` + +Try out a low threshold and check the results. + +```bash +i.segment group=ortho_group output=ortho_segs_l1 threshold=0.02 +``` + +![](i_segment_ortho_segs_l1.jpg) + +From a visual inspection, it seems this results in too many segments. +Increasing the threshold, using the previous results as seeds, and +setting a minimum size of 2: + +```bash +i.segment group=ortho_group output=ortho_segs_l2 threshold=0.05 seeds=ortho_segs_l1 min=2 + +i.segment group=ortho_group output=ortho_segs_l3 threshold=0.1 seeds=ortho_segs_l2 + +i.segment group=ortho_group output=ortho_segs_l4 threshold=0.2 seeds=ortho_segs_l3 + +i.segment group=ortho_group output=ortho_segs_l5 threshold=0.3 seeds=ortho_segs_l4 +``` + +![](i_segment_ortho_segs_l2_l5.jpg) + +The output `ortho_segs_l4` with **threshold**=0.2 still has too many +segments, but the output with **threshold**=0.3 has too few segments. A +threshold value of 0.25 seems to be a good choice. There is also some +noise in the image, lets next force all segments smaller than 10 pixels +to be merged into their most similar neighbor (even if they are less +similar than required by our threshold): + +Set the region to match the entire map(s) in the group. + +```bash +g.region -p raster=ortho_2001_t792_1m@PERMANENT +``` + +Run *i.segment* on the full map: + +```bash +i.segment group=ortho_group output=ortho_segs_final threshold=0.25 min=10 +``` + +![](i_segment_ortho_segs_final.jpg) + +Processing the entire ortho image with nearly 10 million pixels took +about 450 times more then for the final run. + +### Segmentation of panchromatic channel + +This example uses the panchromatic channel of the Landsat7 scene +included in the North Carolina sample dataset: + +```bash +# create group with single channel +i.group group=singleband input=lsat7_2002_80 + +# set computational region to Landsat7 PAN band +g.region raster=lsat7_2002_80 -p + +# perform segmentation with minsize=5 +i.segment group=singleband threshold=0.05 minsize=5 \ + output=lsat7_2002_80_segmented_min5 goodness=lsat7_2002_80_goodness_min5 + +# perform segmentation with minsize=100 +i.segment group=singleband threshold=0.05 minsize=100 + output=lsat7_2002_80_segmented_min100 goodness=lsat7_2002_80_goodness_min100 +``` + +![](i_segment_lsat7_pan.png) +Original panchromatic channel of the Landsat7 scene + +![](i_segment_lsat7_seg_min5.png) +Segmented panchromatic channel, minsize=5 + +![](i_segment_lsat7_seg_min100.png) +Segmented panchromatic channel, minsize=100 + +## TODO + +### Functionality + +- Further testing of the shape characteristics (smoothness, + compactness), if it looks good it should be added. (**in progress**) +- Malahanobis distance for the similarity calculation. + +### Use of Segmentation Results + +- Providing updates to *[i.maxlik](i.maxlik.md)* to ensure the + segmentation output can be used as input for the existing + classification functionality. +- Integration/workflow for *r.fuzzy* (Addon). + +### Speed + +- See create_isegs.c + +## REFERENCES + +This project was first developed during GSoC 2012. Project +documentation, Image Segmentation references, and other information is +at the [project +wiki](https://grasswiki.osgeo.org/wiki/GRASS_GSoC_2012_Image_Segmentation). + +Information about [classification in +GRASS](https://grasswiki.osgeo.org/wiki/Image_classification) is at +available on the wiki. + +## SEE ALSO + +*[i.segment.stats](https://grass.osgeo.org/grass8/manuals/addons/i.segment.stats.html) +(addon), +[i.segment.uspo](https://grass.osgeo.org/grass8/manuals/addons/i.segment.uspo.html) +(addon), +[i.segment.hierarchical](https://grass.osgeo.org/grass8/manuals/addons/i.segment.hierarchical.html) +(addon) [g.gui.iclass](g.gui.iclass.md), [i.group](i.group.md), +[i.maxlik](i.maxlik.md), [i.smap](i.smap.md), [r.kappa](r.kappa.md)* + +## AUTHORS + +Eric Momsen - North Dakota State University +Markus Metz (GSoC Mentor) diff --git a/imagery/i.signatures/i.signatures.md b/imagery/i.signatures/i.signatures.md new file mode 100644 index 00000000000..a07bbd78919 --- /dev/null +++ b/imagery/i.signatures/i.signatures.md @@ -0,0 +1,58 @@ +## DESCRIPTION + +*i.signatures* module allows managing signature files: + +- "sig" – generated by [i.gensig](i.gensig.md) for + [i.maxlik](i.maxlik.md) +- "sigset" – generated by [i.gensigset](i.gensigset.md) for + [i.smap](i.smap.md) + +The module can perform multiple actions per run. The order of execution +is "copy", "remove", "rename". When the print flag is specified without +specifying any type of signature files, it would print all signatures +grouped by type. + +## NOTES + +By default the module will list signature files from all mapsets in the +current search path. It is possible to limit listing only to a single +mapset by providing the "mapset" option. The mapset can be also not +listed in the current search path. +Actions "remove" and "rename" operate only on the current mapset +(although accept fully qualified names). The "copy" action will accept a +signature file name from any mapset as its first argument (source file +to copy). + +## EXAMPLES + +Print names of all signature files: + +```bash +i.signatures -p +``` + +Print only signature files of certain type as a JSON: + +```bash +i.signatures -p type=sigset format=json +``` + +Delete signature file called "foo" of type "sig" (i.gensig / i.maxlik). + +```bash +i.signatures remove=foo type=sig +``` + +Copy signature file "bar" from mapset "baz" to current mapset + +```bash +i.signatures copy=bar@baz,best_version type=sigset +``` + +## SEE ALSO + +*[i.gensig](i.gensig.md) [i.gensigset](i.gensigset.md)* + +## AUTHOR + +Maris Nartiss diff --git a/imagery/i.smap/i.smap.md b/imagery/i.smap/i.smap.md new file mode 100644 index 00000000000..7cccd19b03a --- /dev/null +++ b/imagery/i.smap/i.smap.md @@ -0,0 +1,192 @@ +## DESCRIPTION + +The *i.smap* program is used to segment multispectral images using a +spectral class model known as a Gaussian mixture distribution. Since +Gaussian mixture distributions include conventional multivariate +Gaussian distributions, this program may also be used to segment +multispectral images based on simple spectral mean and covariance +parameters. + +*i.smap* has two modes of operation. The first mode is the sequential +maximum a posteriori (SMAP) mode (see Bouman and Shapiro, 1992; Bouman +and Shapiro, 1994). The SMAP segmentation algorithm attempts to improve +segmentation accuracy by segmenting the image into regions rather than +segmenting each pixel separately (see NOTES below). + +The second mode is the more conventional maximum likelihood (ML) +classification which classifies each pixel separately, but requires +somewhat less computation. This mode is selected with the **-m** flag +(see below). + +## OPTIONS + +### Flags + +**-m** +Use maximum likelihood estimation (instead of smap). Normal operation is +to use SMAP estimation (see NOTES below). + +### Parameters + +**group=***name* +imagery group +The imagery group that defines the image to be classified. + +**subgroup=***name* +imagery subgroup +The subgroup within the group specified that specifies the subset of the +band files that are to be used as image data to be classified. + +**signaturefile=***name* +imagery signaturefile +The signature file that contains the spectral signatures (i.e., the +statistics) for the classes to be identified in the image. This +signature file is produced by the program +*[i.gensigset](i.gensigset.md)* (see NOTES below). + +**blocksize=***value* +size of submatrix to process at one time +default: 1024 +This option specifies the size of the "window" to be used when reading +the image data. + +This program was written to be nice about memory usage without +influencing the resultant classification. This option allows the user to +control how much memory is used. More memory may mean faster (or slower) +operation depending on how much real memory your machine has and how +much virtual memory the program uses. + +The size of the submatrix used in segmenting the image has a principle +function of controlling memory usage; however, it also can have a subtle +effect on the quality of the segmentation in the smap mode. The +smoothing parameters for the smap segmentation are estimated separately +for each submatrix. Therefore, if the image has regions with +qualitatively different behavior, (e.g., natural woodlands and man-made +agricultural fields) it may be useful to use a submatrix small enough so +that different smoothing parameters may be used for each distinctive +region of the image. + +The submatrix size has no effect on the performance of the ML +segmentation method. + +**output=***name* +output raster map. +The name of a raster map that will contain the classification results. +This new raster map layer will contain categories that can be related to +landcover categories on the ground. + +## NOTES + +The SMAP algorithm exploits the fact that nearby pixels in an image are +likely to have the same class. It works by segmenting the image at +various scales or resolutions and using the coarse scale segmentations +to guide the finer scale segmentations. In addition to reducing the +number of misclassifications, the SMAP algorithm generally produces +segmentations with larger connected regions of a fixed class which may +be useful in some applications. + +The amount of smoothing that is performed in the segmentation is +dependent of the behaviour of the data in the image. If the data +suggests that the nearby pixels often change class, then the algorithm +will adaptively reduce the amount of smoothing. This ensures that +excessively large regions are not formed. + +The degree of misclassifications can be investigated with the goodness +of fit output map. Lower values indicate a better fit. The largest 5 to +15% of the goodness values may need some closer inspection. + +The module *i.smap* does not support MASKed or NULL cells. Therefore it +might be necessary to create a copy of the classification results using +e.g. *r.mapcalc*: + +```bash +r.mapcalc "MASKed_map = classification_results" +``` + +## EXAMPLE + +Supervised classification of LANDSAT scene (complete NC dataset) + +```bash +# Align computation region to the scene +g.region raster=lsat7_2002_10 -p + +# store VIZ, NIR, MIR into group/subgroup +i.group group=lsat7_2002 subgroup=res_30m \ + input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 + +# Now digitize training areas "training" with the digitizer +# and convert to raster model with v.to.rast +v.to.rast input=training output=training use=cat label_column=label +# If you are just playing around and do not care about the accuracy of outcome, +# just use one of existing maps instead e.g. +# g.copy rast=landuse96_28m,training + +# Create a signature file with statistics for each class +i.gensigset trainingmap=training group=lsat7_2002 subgroup=res_30m \ + signaturefile=lsat7_2002_30m maxsig=5 + +# Predict classes based on whole LANDSAT scene +i.smap group=lsat7_2002 subgroup=res_30m signaturefile=lsat7_2002_30m \ + output=lsat7_2002_smap_classes + +# Visually check result +d.mon wx0 +d.rast.leg lsat7_2002_smap_classes + +# Statistically check result +r.kappa -w classification=lsat7_2002_smap_classes reference=training +``` + +The signature file obtained in the example above will allow to classify +the current imagery group only (lsat7_2002). If the user would like to +re-use the signature file for the classification of different imagery +group(s), they can set semantic labels for each group member beforehand, +i.e., before generating the signature files. Semantic labels are set by +means of *r.support* as shown below: + +```bash +# Define semantic labels for all LANDSAT bands +r.support map=lsat7_2002_10 semantic_label=TM7_1 +r.support map=lsat7_2002_20 semantic_label=TM7_2 +r.support map=lsat7_2002_30 semantic_label=TM7_3 +r.support map=lsat7_2002_40 semantic_label=TM7_4 +r.support map=lsat7_2002_50 semantic_label=TM7_5 +r.support map=lsat7_2002_61 semantic_label=TM7_61 +r.support map=lsat7_2002_62 semantic_label=TM7_62 +r.support map=lsat7_2002_70 semantic_label=TM7_7 +r.support map=lsat7_2002_80 semantic_label=TM7_8 +``` + +## REFERENCES + +- C. Bouman and M. Shapiro, "Multispectral Image Segmentation using a + Multiscale Image Model", *Proc. of IEEE Int'l Conf. on Acoust., Speech + and Sig. Proc.,* pp. III-565 - III-568, San Francisco, California, + March 23-26, 1992. +- C. Bouman and M. Shapiro 1994, "A Multiscale Random Field Model for + Bayesian Image Segmentation", *IEEE Trans. on Image Processing., 3(2), + 162-177" + ([PDF](http://dynamo.ecn.purdue.edu/~bouman/publications/pdf/ip2.pdf))* +- McCauley, J.D. and B.A. Engel 1995, "Comparison of Scene + Segmentations: SMAP, ECHO and Maximum Likelihood", *IEEE Trans. on + Geoscience and Remote Sensing, 33(6): 1313-1316.* + +## SEE ALSO + +*[r.support](r.support.md)* for setting semantic labels, +*[i.group](i.group.md)* for creating groups and subgroups, +*[r.mapcalc](r.mapcalc.md)* to copy classification result in order to +cut out MASKed subareas, +*[i.gensigset](i.gensigset.md)* to generate the signature file required +by this program + +*[g.gui.iclass](g.gui.iclass.md), [i.maxlik](i.maxlik.md), +[r.kappa](r.kappa.md)* + +## AUTHORS + +[Charles Bouman, School of Electrical Engineering, Purdue +University](https://engineering.purdue.edu/~bouman/software/segmentation/) +Michael Shapiro, U.S.Army Construction Engineering Research Laboratory +Semantic label support: Maris Nartiss, University of Latvia diff --git a/imagery/i.svm.predict/i.svm.predict.md b/imagery/i.svm.predict/i.svm.predict.md new file mode 100644 index 00000000000..5934d5a0f89 --- /dev/null +++ b/imagery/i.svm.predict/i.svm.predict.md @@ -0,0 +1,70 @@ +## DESCRIPTION + +*i.svm.predict* predicts values with a Support Vector Machine (SVM) and +stores them in a raster file. Predictions are based on a signature file +generated with [i.svm.train](i.svm.train.md). + +Internally the module performs input value rescaling of each of imagery +group rasters by minimum and maximum range determined during training. + +## NOTES + +*i.svm.train* internally is using the LIBSVM. For introduction into +value prediction or estimation with LIBSVM, see [a Practical Guide to +Support Vector +Classification](https://www.csie.ntu.edu.tw/~cjlin/papers/guide/guide.pdf) +by Chih-Wei Hsu, Chih-Chung Chang, and Chih-Jen Lin. + +It is strongly suggested to have semantic labels set for each raster map +in the training data (feature value) and in value prediction imagery +groups. Use [r.support](r.support.md) to set semantic labels. + +## PERFORMANCE + +Value prediction is done cell by cell and thus memory consumption should +be constant. + +The *cache* parameter determines the maximum memory allocated for kernel +caching to enhance computational speed. It's important to note that the +actual module's memory consumption may vary from this setting, as it +solely impacts LIBSVM's internal caching. The cache is utilized on an +as-needed basis, so it's unlikely to reach the specified value. + +## EXAMPLE + +This is the second part of classification process. See +[i.svm.train](i.svm.train.md) for the first part. + +Predict land use classes form a LANDSAT scene from October of 2002 with +a SVM trained on a 1996 land use map *landuse96_28m*. + +```bash +i.svm.predict group=lsat7_2002 subgroup=res_30m \ + signaturefile=landuse96_rnd_points output=pred_landuse_2002 +``` + +## SEE ALSO + +*Train SVM: [i.svm.train](i.svm.train.md) +Set semantic labels: [r.support](r.support.md) +Other classification modules: [i.maxlik](i.maxlik.md), +[i.smap](i.smap.md)* +LIBSVM home page: [LIBSVM - A Library for Support Vector +Machines](https://www.csie.ntu.edu.tw/~cjlin/libsvm/) + +## REFERENCES + +Please cite both - LIBSVM and i.svm. + +- For i.svm.\* modules: + Nartiss, M., & Melniks, R. (2023). Improving pixel-­based + classification of GRASS GIS with support vector machine. Transactions + in GIS, 00, 1–16. +- For LIBSVM: + Chang, C.-C., & Lin, C.-J. (2011). LIBSVM : a library for support + vector machines. ACM Transactions on Intelligent Systems and + Technology, 2:27:1--27:27. + +## AUTHOR + +Maris Nartiss, University of Latvia. diff --git a/imagery/i.svm.train/i.svm.train.md b/imagery/i.svm.train/i.svm.train.md new file mode 100644 index 00000000000..ab257c9c475 --- /dev/null +++ b/imagery/i.svm.train/i.svm.train.md @@ -0,0 +1,100 @@ +## DESCRIPTION + +*i.svm.train* finds parameters for a Support Vector Machine and stores +them in a signature file for later usage by +[i.svm.predict](i.svm.predict.md). + +Internally the module performs input value rescaling of each of imagery +group rasters by mean normalisation based on minimum and maximum value +present in the raster metadata. Rescaling parameters are written into +the signature file for use during prediction. + +## NOTES + +*i.svm.train* internally is using the LIBSVM. For introduction into +value prediction or estimation with LIBSVM, see [a Practical Guide to +Support Vector +Classification](https://www.csie.ntu.edu.tw/~cjlin/papers/guide/guide.pdf) +by Chih-Wei Hsu, Chih-Chung Chang, and Chih-Jen Lin. + +It is strongly suggested to have semantic labels set for each raster map +in the training data (feature value) imagery group. Use +[r.support](r.support.md) to set semantic labels. + +## PERFORMANCE + +SVM training is done by loading all training data into memory. In a case +of large input raster files, use sparse label rasters (e.g. raster +points or small patches instead of uninterrupted cover). + +During the training process there is no progress output printed. +Training with large number of data points can take significant time - +just be patient. + +By default the shrinking heuristics option of LIBSVM is enabled. It +should not impact the outcome, just the training time. On some input +parameter and data combinations training with the shrinking heuristics +disabled might be faster. + +The *cache* parameter determines the maximum memory allocated for kernel +caching to enhance computational speed. It's important to note that the +actual module's memory consumption may vary from this setting, as it +solely impacts LIBSVM's internal caching. The cache is utilized on an +as-needed basis, so it's unlikely to reach the specified value. + +## EXAMPLE + +This is the first part of classification process. See +[i.svm.predict](i.svm.predict.md) for the second part. + +Train a SVM to identify land use classes according to the 1996 land use +map *landuse96_28m* and then classify a LANDSAT scene from October of +2002. Example requires the nc_spm_08 dataset. + +```bash +# Align computation region to the scene +g.region raster=lsat7_2002_10 -p + +# store VIZ, NIR, MIR into group/subgroup +i.group group=lsat7_2002 subgroup=res_30m \ + input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 + +# Now digitize training areas "training" with the digitizer +# and convert to raster model with v.to.rast +v.to.rast input=training output=training use=cat label_column=label +# If you are just playing around and do not care about the accuracy of outcome, +# just use one of existing maps instead e.g. +# r.random input=landuse96_28m npoints=10000 raster=training -s + +# Train the SVM +i.svm.train group=lsat7_2002 subgroup=res_30m \ + trainingmap=training signaturefile=landuse96_rnd_points + +# Go to i.svm.predict for the next step. +``` + +## SEE ALSO + +*Predict values: [i.svm.predict](i.svm.predict.md) +Set semantic labels: [r.support](r.support.md) +Other classification modules: [i.maxlik](i.maxlik.md), +[i.smap](i.smap.md)* +LIBSVM home page: [LIBSVM - A Library for Support Vector +Machines](https://www.csie.ntu.edu.tw/~cjlin/libsvm/) + +## REFERENCES + +Please cite both - LIBSVM and i.svm. + +- For i.svm.\* modules: + Nartiss, M., & Melniks, R. (2023). Improving pixel-­based + classification of GRASS GIS with support vector machine. Transactions + in GIS, 00, 1–16. +- For LIBSVM: + Chang, C.-C., & Lin, C.-J. (2011). LIBSVM : a library for support + vector machines. ACM Transactions on Intelligent Systems and + Technology, 2:27:1--27:27. + +## AUTHOR + +Maris Nartiss, University of Latvia. diff --git a/imagery/i.target/i.target.md b/imagery/i.target/i.target.md new file mode 100644 index 00000000000..6daf6ecadd4 --- /dev/null +++ b/imagery/i.target/i.target.md @@ -0,0 +1,33 @@ +## DESCRIPTION + +*i.target* targets an [imagery group](i.group.md) to a GRASS data base +project name and mapset. A project name and mapset are required for the +*[i.rectify](i.rectify.md)* imagery module, into which to write the +rectified map just prior to completion of the program; *i.target* +enables the user to specify this project. *i.target* must be run before +*[g.gui.gcp](g.gui.gcp.md)* and *[i.rectify](i.rectify.md)*. + +## NOTES + +The module's first option asks for the name of the [imagery +group](i.group.md) that needs a target. The imagery group must be +present in the user's current mapset. An [imagery group](i.group.md) may +be targeted to any GRASS project. + +If a group name is given without setting options, the currently targeted +group will be displayed. + +## SEE ALSO + +The GRASS 4 *[Image Processing +manual](https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf)* + +*[g.gui.gcp](g.gui.gcp.md), [i.group](i.group.md), +[i.rectify](i.rectify.md)* +*[Manage Ground Control Points](wxGUI.gcp.md)* + +## AUTHORS + +Michael Shapiro, U.S. Army Construction Engineering Research Laboratory + +Parser support: Bob Covill diff --git a/imagery/i.topo.corr/i.topo.corr.md b/imagery/i.topo.corr/i.topo.corr.md new file mode 100644 index 00000000000..5528d2ef13d --- /dev/null +++ b/imagery/i.topo.corr/i.topo.corr.md @@ -0,0 +1,114 @@ +## DESCRIPTION + +*i.topo.corr* is used to topographically correct reflectance from +imagery files, e.g. obtained with *i.landsat.toar*, using a sun +illumination terrain model. This illumination model represents the +cosine of the incident angle *i*, i.e. the angle between the normal to +the ground and the sun rays. + +Note: If needed, the sun position can be calculated for a given date and +time with *r.sunmask*. + +![Figure showing terrain and solar angles](i_topo_corr_angles.png) +Figure showing terrain and solar angles + +Using the **-i** flag and given an elevation basemap (metric), +*i.topo.corr* creates a simple illumination model using the formula: + +- cos_i = cos(s) \* cos(z) + sin(s) \* sin(z) \* cos(a - o) + +where, + +- *i* is the incident angle to be calculated, +- *s* is the terrain slope angle (from *r.slope.aspect*), +- *z* is the solar zenith angle (i.e., 90° - solar horizon angle from + *r.sunmask*), +- *a* the solar azimuth angle (from *r.sunmask*), +- *o* the terrain aspect angle (from *r.slope.aspect*). + +For each band file, the corrected reflectance (ref_c) is calculate from +the original reflectance (ref_o) using one of the four offered methods +(one lambertian and two non-lambertian). + +### Method: cosine + +- ref_c = ref_o \* cos_z / cos_i + +### Method: minnaert + +- ref_c = ref_o \* (cos_z / cos_i) ^k + +where, *k* is obtained by linear regression of +ln(ref_o) = ln(ref_c) - k ln(cos_i/cos_z) + +### Method: c-factor + +- ref_c = ref_o \* (cos_z + c)/ (cos_i + c) + +where, *c* is a/m from ref_o = a + m \* cos_i + +### Method: percent + +We can use cos_i to estimate the percent of solar incidence on the +surface, then the transformation (cos_i + 1)/2 varied from 0 (surface in +the side in opposition to the sun: infinite correction) to 1 (direct +exhibition to the sun: no correction) and the corrected reflectance can +be calculated as + +- ref_c = ref_o \* 2 / (cos_i + 1) + +## NOTES + +1. The illumination model (cos_i) with flag -i uses the actual region + as limits and the resolution of the elevation map. +2. The topographic correction use the full reflectance file (null + remain null) and its resolution. +3. The elevation map to calculate the illumination model should be + metric. + +## EXAMPLES + +First, make a illumination model from the elevation map (here, SRTM). +Then make perform the topographic correction of e.g. the bands toar.5, +toar.4 and toar.3 with output as tcor.toar.5, tcor.toar.4, and +tcor.toar.3 using c-factor (= c-correction) method: + +```bash +# first pass: create illumination model +i.topo.corr -i base=SRTM zenith=33.3631 azimuth=59.8897 output=SRTM.illumination + +# second pass: apply illumination model +i.topo.corr base=SRTM.illumination input=toar.5,toar.4,toar.3 output=tcor \ + zenith=33.3631 method=c-factor +``` + +## REFERENCES + +- Law K.H. and Nichol J, 2004. Topographic Correction For Differential + Illumination Effects On Ikonos Satellite Imagery. International + Archives of Photogrammetry Remote Sensing and Spatial Information, pp. + 641-646. +- Meyer, P. and Itten, K.I. and Kellenberger, KJ and Sandmeier, S. and + Sandmeier, R., 1993. Radiometric corrections of topographically + induced effects on Landsat TM data in alpine terrain. Photogrammetric + Engineering and Remote Sensing 48(17). +- Riaño, D. and Chuvieco, E. and Salas, J. and Aguado, I., 2003. + Assessment of Different Topographic Corrections in Landsat-TM Data for + Mapping Vegetation Types. IEEE Transactions On Geoscience And Remote + Sensing, Vol. 41, No. 5 +- Twele A. and Erasmi S, 2005. Evaluating topographic correction + algorithms for improved land cover discrimination in mountainous areas + of Central Sulawesi. Göttinger Geographische Abhandlungen, vol. 113. + +## SEE ALSO + +*[i.landsat.toar](i.landsat.toar.md), [r.mapcalc](r.mapcalc.md), +[r.sun](r.sun.md) [r.sunmask](r.sunmask.md)* + +## AUTHOR + +E. Jorge Tizado (ej.tizado unileon es) +Dept. Biodiversity and Environmental Management, University of León, +Spain + +Figure derived from Neteler & Mitasova, 2008. diff --git a/imagery/i.vi/i.vi.md b/imagery/i.vi/i.vi.md new file mode 100644 index 00000000000..ccf38c3ab48 --- /dev/null +++ b/imagery/i.vi/i.vi.md @@ -0,0 +1,551 @@ +## DESCRIPTION + +*i.vi* calculates vegetation indices based on biophysical parameters. + +- ARVI: Atmospherically Resistant Vegetation Index +- CI: Crust Index +- DVI: Difference Vegetation Index +- EVI: Enhanced Vegetation Index +- EVI2: Enhanced Vegetation Index 2 +- GARI: Green atmospherically resistant vegetation index +- GEMI: Global Environmental Monitoring Index +- GVI: Green Vegetation Index +- IPVI: Infrared Percentage Vegetation Index +- MSAVI2: second Modified Soil Adjusted Vegetation Index +- MSAVI: Modified Soil Adjusted Vegetation Index +- NDVI: Normalized Difference Vegetation Index +- NDWI: Normalized Difference Water Index +- PVI: Perpendicular Vegetation Index +- RVI: ratio vegetation index +- SAVI: Soil Adjusted Vegetation Index +- SR: Simple Vegetation ratio +- WDVI: Weighted Difference Vegetation Index + +### Background for users new to remote sensing + +Vegetation Indices are often considered the entry point of remote +sensing for Earth land monitoring. They are suffering from their +success, in terms that often people tend to harvest satellite images +from online sources and use them directly in this module. + +From Digital number to Radiance: +Satellite imagery is commonly stored in Digital Number (DN) for storage +purposes; e.g., Landsat5 data is stored in 8bit values (ranging from 0 +to 255), other satellites maybe stored in 10 or 16 bits. If the data is +provided in DN, this implies that this imagery is "uncorrected". What +this means is that the image is what the satellite sees at its position +and altitude in space (stored in DN). This is not the signal at ground +yet. We call this data at-satellite or at-sensor. Encoded in the 8bits +(or more) is the amount of energy sensed by the sensor inside the +satellite platform. This energy is called radiance-at-sensor. Generally, +satellites image providers encode the radiance-at-sensor into 8bit (or +more) through an affine transform equation (y=ax+b). In case of using +Landsat imagery, look at the *i.landsat.toar* for an easy way to +transform DN to radiance-at-sensor. If using Aster data, try the +*i.aster.toar* module. + +From Radiance to Reflectance: +Finally, once having obtained the radiance at sensor values, still the +atmosphere is between sensor and Earth's surface. This fact needs to be +corrected to account for the atmospheric interaction with the sun energy +that the vegetation reflects back into space. This can be done in two +ways for Landsat. The simple way is through *i.landsat.toar*, use e.g. +the DOS correction. The more accurate way is by using *i.atcorr* (which +works for many satellite sensors). Once the atmospheric correction has +been applied to the satellite data, data vales are called surface +reflectance. Surface reflectance is ranging from 0.0 to 1.0 +theoretically (and absolutely). This level of data correction is the +proper level of correction to use with *i.vi*. + +### Vegetation Indices + +**ARVI: Atmospheric Resistant Vegetation Index** + +ARVI is resistant to atmospheric effects (in comparison to the NDVI) and +is accomplished by a self correcting process for the atmospheric effect +in the red channel, using the difference in the radiance between the +blue and the red channels (Kaufman and Tanre 1996). + +```bash +arvi( redchan, nirchan, bluechan ) + +ARVI = (nirchan - (2.0*redchan - bluechan)) / + ( nirchan + (2.0*redchan - bluechan)) +``` + +**CI: Crust Index** + +Advantage is taken of a unique spectral feature of soil biogenic crust +containing cyanobacteria. It has been shown that the special phycobilin +pigment in cyanobacteria contributes in producing a relatively higher +reflectance in the blue spectral region than the same type of substrate +without the biogenic crust. The spectral crust index (CI) is based on +the normalized difference between the RED and the BLUE spectral values +(Karnieli, 1997, DOI: 10.1080/014311697218368). + +```bash +ci ( bluechan, redchan ) + +CI = 1 - (redchan - bluechan) / + (redchan + bluechan) +``` + +**DVI: Difference Vegetation Index** + +```bash +dvi( redchan, nirchan ) + +DVI = ( nirchan - redchan ) +``` + +**EVI: Enhanced Vegetation Index** + +The enhanced vegetation index (EVI) is an optimized index designed to +enhance the vegetation signal with improved sensitivity in high biomass +regions and improved vegetation monitoring through a de-coupling of the +canopy background signal and a reduction in atmosphere influences (Huete +A.R., Liu H.Q., Batchily K., van Leeuwen W. (1997). A comparison of +vegetation indices global set of TM images for EOS-MODIS. Remote Sensing +of Environment, 59:440-451). + +```bash +evi( bluechan, redchan, nirchan ) + +EVI = 2.5 * ( nirchan - redchan ) / + ( nirchan + 6.0 * redchan - 7.5 * bluechan + 1.0 ) +``` + +**EVI2: Enhanced Vegetation Index 2** + +A 2-band EVI (EVI2), without a blue band, which has the best similarity +with the 3-band EVI, particularly when atmospheric effects are +insignificant and data quality is good (Zhangyan Jiang ; Alfredo R. +Huete ; Youngwook Kim and Kamel Didan 2-band enhanced vegetation index +without a blue band and its application to AVHRR data. Proc. SPIE 6679, +Remote Sensing and Modeling of Ecosystems for Sustainability IV, 667905 +(october 09, 2007) +[doi:10.1117/12.734933](https://doi.org/10.1117/12.734933)). + +```bash +evi2( redchan, nirchan ) + +EVI2 = 2.5 * ( nirchan - redchan ) / + ( nirchan + 2.4 * redchan + 1.0 ) +``` + +**GARI: green atmospherically resistant vegetation index** + +The formula was actually defined: Gitelson, Anatoly A.; Kaufman, Yoram +J.; Merzlyak, Mark N. (1996) Use of a green channel in remote sensing of +global vegetation from EOS- MODIS, Remote Sensing of Environment 58 (3), +289-298. +[doi:10.1016/s0034-4257(96)00072-7](https://doi.org/10.1016/s0034-4257(96)00072-7) + +```bash +gari( redchan, nirchan, bluechan, greenchan ) + +GARI = ( nirchan - (greenchan - (bluechan - redchan))) / + ( nirchan + (greenchan - (bluechan - redchan))) +``` + +**GEMI: Global Environmental Monitoring Index** + +```bash +gemi( redchan, nirchan ) + +GEMI = (( (2*((nirchan * nirchan)-(redchan * redchan)) + + 1.5*nirchan+0.5*redchan) / (nirchan + redchan + 0.5)) * + (1 - 0.25 * (2*((nirchan * nirchan)-(redchan * redchan)) + + 1.5*nirchan+0.5*redchan) / (nirchan + redchan + 0.5))) - + ( (redchan - 0.125) / (1 - redchan)) +``` + +**GVI: Green Vegetation Index** + +```bash +gvi( bluechan, greenchan, redchan, nirchan, chan5chan, chan7chan) + +GVI = ( -0.2848 * bluechan - 0.2435 * greenchan - + 0.5436 * redchan + 0.7243 * nirchan + 0.0840 * chan5chan- + 0.1800 * chan7chan) +``` + +**IPVI: Infrared Percentage Vegetation Index** + +```bash +ipvi( redchan, nirchan ) + +IPVI = nirchan/(nirchan+redchan) +``` + +**MSAVI2: second Modified Soil Adjusted Vegetation Index** + +```bash +msavi2( redchan, nirchan ) + +MSAVI2 = (1/2)*(2*NIR+1-sqrt((2*NIR+1)^2-8*(NIR-red))) +``` + +**MSAVI: Modified Soil Adjusted Vegetation Index** + +```bash +msavi( redchan, nirchan ) + +MSAVI = s(NIR-s*red-a) / (a*NIR+red-a*s+X*(1+s*s)) +``` + +where a is the soil line intercept, s is the soil line slope, and X is +an adjustment factor which is set to minimize soil noise (0.08 in +original papers). + +**NDVI: Normalized Difference Vegetation Index** + +```bash +ndvi( redchan, nirchan ) + + +Satellite specific band numbers ([NIR, Red]): + MSS Bands = [ 7, 5] + TM1-5,7 Bands = [ 4, 3] + TM8 Bands = [ 5, 4] + Sentinel-2 Bands = [ 8, 4] + AVHRR Bands = [ 2, 1] + SPOT XS Bands = [ 3, 2] + AVIRIS Bands = [51, 29] + +NDVI = (NIR - Red) / (NIR + Red) +``` + +**NDWI: Normalized Difference Water Index** (after McFeeters, 1996) + +This index is suitable to detect water bodies. + +```bash +ndwi( greenchan, nirchan ) + +NDWI = (green - NIR) / (green + NIR) +``` + +The water content of leaves can be estimated with another NDWI (after +Gao, 1996): + +```bash +ndwi( greenchan, nirchan ) + +NDWI = (NIR - SWIR) / (NIR + SWIR) +``` + +This index is important for monitoring vegetation health (not +implemented). + +**PVI: Perpendicular Vegetation Index** + +```bash +pvi( redchan, nirchan, soil_line_slope ) + +PVI = sin(a)NIR-cos(a)red +``` + +**SAVI: Soil Adjusted Vegetation Index** + +```bash +savi( redchan, nirchan ) + +SAVI = ((1.0+0.5)*(nirchan - redchan)) / (nirchan + redchan +0.5) +``` + +**SR: Simple Vegetation ratio** + +```bash +sr( redchan, nirchan ) + +SR = (nirchan/redchan) +``` + +**VARI: Visible Atmospherically Resistant Index** VARI was designed to +introduce an atmospheric self-correction (Gitelson A.A., Kaufman Y.J., +Stark R., Rundquist D., 2002. Novel algorithms for estimation of +vegetation fraction Remote Sensing of Environment (80), pp76-87.) + +```bash +vari = ( bluechan, greenchan, redchan ) + +VARI = (green - red ) / (green + red - blue) +``` + +**WDVI: Weighted Difference Vegetation Index** + +```bash +wdvi( redchan, nirchan, soil_line_weight ) + +WDVI = nirchan - a * redchan +if(soil_weight_line == None): + a = 1.0 #slope of soil line +``` + +## EXAMPLES + +### Calculation of DVI + +The calculation of DVI from the reflectance values is done as follows: + +```bash +g.region raster=band.1 -p +i.vi blue=band.1 red=band.3 nir=band.4 viname=dvi output=dvi +r.univar -e dvi +``` + +### Calculation of EVI + +The calculation of EVI from the reflectance values is done as follows: + +```bash +g.region raster=band.1 -p +i.vi blue=band.1 red=band.3 nir=band.4 viname=evi output=evi +r.univar -e evi +``` + +### Calculation of EVI2 + +The calculation of EVI2 from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=evi2 output=evi2 +r.univar -e evi2 +``` + +### Calculation of GARI + +The calculation of GARI from the reflectance values is done as follows: + +```bash +g.region raster=band.1 -p +i.vi blue=band.1 green=band.2 red=band.3 nir=band.4 viname=gari output=gari +r.univar -e gari +``` + +### Calculation of GEMI + +The calculation of GEMI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=gemi output=gemi +r.univar -e gemi +``` + +### Calculation of GVI + +The calculation of GVI (Green Vegetation Index - Tasseled Cap) from the +reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +# assuming Landsat-7 +i.vi blue=band.1 green=band.2 red=band.3 nir=band.4 band5=band.5 band7=band.7 viname=gvi output=gvi +r.univar -e gvi +``` + +### Calculation of IPVI + +The calculation of IPVI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=ipvi output=ipvi +r.univar -e ipvi +``` + +### Calculation of MSAVI + +The calculation of MSAVI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=msavi output=msavi +r.univar -e msavi +``` + +### Calculation of NDVI + +The calculation of NDVI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=ndvi output=ndvi +r.univar -e ndvi +``` + +### Calculation of NDWI + +The calculation of NDWI from the reflectance values is done as follows: + +```bash +g.region raster=band.2 -p +i.vi green=band.2 nir=band.4 viname=ndwi output=ndwi +r.colors ndwi color=byg -n +r.univar -e ndwi +``` + +### Calculation of PVI + +The calculation of PVI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 soil_line_slope=0.45 viname=pvi output=pvi +r.univar -e pvi +``` + +### Calculation of SAVI + +The calculation of SAVI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=savi output=savi +r.univar -e savi +``` + +### Calculation of SR + +The calculation of SR from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi red=band.3 nir=band.4 viname=sr output=sr +r.univar -e sr +``` + +### Calculation of VARI + +The calculation of VARI from the reflectance values is done as follows: + +```bash +g.region raster=band.3 -p +i.vi blue=band.2 green=band.3 red=band.4 viname=vari output=vari +r.univar -e vari +``` + +### Landsat TM7 example + +The following examples are based on a LANDSAT TM7 scene included in the +North Carolina sample dataset. + +#### Preparation: DN to reflectance + +As a first step, the original DN (digital number) pixel values must be +converted to reflectance using *i.landsat.toar*. To do so, we make a +copy (or rename the channels) to match *i.landsat.toar*'s input scheme: + +```bash +g.copy raster=lsat7_2002_10,lsat7_2002.1 +g.copy raster=lsat7_2002_20,lsat7_2002.2 +g.copy raster=lsat7_2002_30,lsat7_2002.3 +g.copy raster=lsat7_2002_40,lsat7_2002.4 +g.copy raster=lsat7_2002_50,lsat7_2002.5 +g.copy raster=lsat7_2002_61,lsat7_2002.61 +g.copy raster=lsat7_2002_62,lsat7_2002.62 +g.copy raster=lsat7_2002_70,lsat7_2002.7 +g.copy raster=lsat7_2002_80,lsat7_2002.8 +``` + +Calculation of reflectance values from DN using DOS1 (metadata obtained +from +[p016r035_7x20020524.met.gz](https://grassbook.org/wp-content/uploads/ncexternal/landsat/2002/p016r035_7x20020524.met.gz)): + +```bash +i.landsat.toar input=lsat7_2002. output=lsat7_2002_toar. sensor=tm7 \ + method=dos1 date=2002-05-24 sun_elevation=64.7730999 \ + product_date=2004-02-12 gain=HHHLHLHHL +``` + +The resulting Landsat channels are names +`lsat7_2002_toar.1 .. lsat7_2002_toar.8`. + +#### Calculation of NDVI + +The calculation of NDVI from the reflectance values is done as follows: + +```bash +g.region raster=lsat7_2002_toar.3 -p +i.vi red=lsat7_2002_toar.3 nir=lsat7_2002_toar.4 viname=ndvi \ + output=lsat7_2002.ndvi +r.colors lsat7_2002.ndvi color=ndvi + +d.mon wx0 +d.rast.leg lsat7_2002.ndvi +``` + +![North Carolina dataset: NDVI](i_vi_ndvi.png) +North Carolina dataset: NDVI + +#### Calculation of ARVI + +The calculation of ARVI from the reflectance values is done as follows: + +```bash +g.region raster=lsat7_2002_toar.3 -p +i.vi blue=lsat7_2002_toar.1 red=lsat7_2002_toar.3 nir=lsat7_2002_toar.4 \ + viname=arvi output=lsat7_2002.arvi + +d.mon wx0 +d.rast.leg lsat7_2002.arvi +``` + +![North Carolina dataset: ARVI](i_vi_arvi.png) +North Carolina dataset: ARVI + +#### Calculation of GARI + +The calculation of GARI from the reflectance values is done as follows: + +```bash +g.region raster=lsat7_2002_toar.3 -p +i.vi blue=lsat7_2002_toar.1 green=lsat7_2002_toar.2 red=lsat7_2002_toar.3 \ + nir=lsat7_2002_toar.4 viname=gari output=lsat7_2002.gari + +d.mon wx0 +d.rast.leg lsat7_2002.gari +``` + +![North Carolina dataset: GARI](i_vi_gari.png) +North Carolina dataset: GARI + +## NOTES + +Originally from kepler.gps.caltech.edu +([FAQ](https://web.archive.org/web/20150922165402/http://www.yale.edu/ceo/Documentation/rsvegfaq.html)): + +A FAQ on Vegetation in Remote Sensing +Written by Terrill W. Ray, Div. of Geological and Planetary Sciences, +California Institute of Technology, email: + +Snail Mail: Terrill Ray +Division of Geological and Planetary Sciences +Caltech, Mail Code 170-25 +Pasadena, CA 91125 + +## REFERENCES + +AVHRR, Landsat TM5: + +- Bastiaanssen, W.G.M., 1995. Regionalization of surface flux densities + and moisture indicators in composite terrain; a remote sensing + approach under clear skies in mediterranean climates. PhD thesis, + Wageningen Agricultural Univ., The Netherland, 271 pp. + ([PDF](https://edepot.wur.nl/206553)) +- [Index DataBase: List of available + Indices](https://www.indexdatabase.de/db/i.php) + +## SEE ALSO + +*[i.albedo](i.albedo.md), [i.aster.toar](i.aster.toar.md), +[i.landsat.toar](i.landsat.toar.md), [i.atcorr](i.atcorr.md), +[i.tasscap](i.tasscap.md)* + +## AUTHORS + +Baburao Kamble, Asian Institute of Technology, Thailand +Yann Chemin, Asian Institute of Technology, Thailand diff --git a/imagery/i.zc/i.zc.md b/imagery/i.zc/i.zc.md new file mode 100644 index 00000000000..49cdd59f5d8 --- /dev/null +++ b/imagery/i.zc/i.zc.md @@ -0,0 +1,52 @@ +## DESCRIPTION + +*i.zc* is an image processing module used for edge detection. The raster +map produced shows the location of "boundaries" on the input map. +Boundaries tend to be found in regions of changing cell values and tend +to run perpendicular to the direction of the slope. The algorithm used +for edge detection is one of the "zero-crossing" algorithms and is +discussed briefly below. + +## NOTES + +The procedure to find the "edges" in the image is as follows: + +1. The Fourier transform of the image is taken, +2. The Fourier transform of the Laplacian of a two-dimensional Gaussian + function is used to filter the transformed image, +3. The result is run through an inverse Fourier transform, +4. The resulting image is traversed in search of places where the image + changes from positive to negative or from negative to positive, +5. Each cell in the map where the value crosses zero (with a change in + value greater than the threshold value) is marked as an edge and an + orientation is assigned to it. The resulting raster map layer is + output. + +The **width=** parameter determines the x-y extent of the Gaussian +filter. The default value is **9**; higher and lower values can be +tested by the user. Increasing the width will result in finding "edges" +representing more gradual changes in cell values. + +The **threshold=** parameter determines the "sensitivity" of the +Gaussian filter. The default value is **1**; higher and lower values can +be tested by the user. Increasing the threshold value will result in +fewer edges being found. + +The **orientations=** value is the number of azimuth directions the +cells on the output raster map layer are categorized into (similar to +the aspect raster map layer produced by +*[r.slope.aspect](r.slope.aspect.md)*. For example, a value of **16** +would result in detected edges being categorized into one of 16 bins +depending on the direction of the edge at that point. + +The current region definition and mask settings are respected when +reading the input map. + +## SEE ALSO + +*[i.fft](i.fft.md), [i.ifft](i.ifft.md), [r.mapcalc](r.mapcalc.md), +[r.mfilter](r.mfilter.md), [r.slope.aspect](r.slope.aspect.md)* + +## AUTHOR + +David Satnik, GIS Laboratory, Central Washington University diff --git a/imagery/imageryintro.md b/imagery/imageryintro.md new file mode 100644 index 00000000000..8ba3d80943b --- /dev/null +++ b/imagery/imageryintro.md @@ -0,0 +1,266 @@ +### Image processing in general + +GRASS GIS provides a powerful suite of tools for the processing and +analysis of geospatial raster data, including satellite imagery and +aerial photography. Its image processing capabilities encompass a broad +range of preprocessing operations, such as data import, georeferencing, +radiometric calibration, and atmospheric correction. It is particularly +suited for handling Earth observation data, enabling the analysis of +multispectral and temporal datasets. GRASS GIS supports advanced +functionalities such as image classification, sensor fusion, and point +cloud statistics. The calculation of vegetation indices further enables +analyses of environmental, agricultural, and land cover dynamics. An +extensive collection of +[addons](https://grass.osgeo.org/grass8/manuals/addons/#i) further +enhances its image processing capabilities, particularly in the context +of Earth observation and remote sensing applications. **Digital numbers +and physical values (reflection/radiance-at-sensor):** + +Satellite imagery is commonly stored in Digital Numbers (DN) for +minimizing the storage volume, i.e. the originally sampled analog +physical value (color, temperature, etc) is stored a discrete +representation in 8-16 bits. For example, Landsat data are stored in +8bit values (i.e., ranging from 0 to 255); other satellite data may be +stored in 10 or 16 bits. Having data stored in DN, it implies that these +data are not yet the observed ground reality. Such data are called +"at-satellite", for example the amount of energy sensed by the sensor of +the satellite platform is encoded in 8 or more bits. This energy is +called radiance-at-sensor. To obtain physical values from DNs, satellite +image providers use a linear transform equation `(y = a * x + b)` to +encode the radiance-at-sensor in 8 to 16 bits. DNs can be turned back +into physical values by applying the reverse formula +`(x = (y - b) / a)`. + +The GRASS GIS module [i.landsat.toar](i.landsat.toar.md) easily +transforms Landsat DN to radiance-at-sensor (top of atmosphere, TOA). +The equivalent module for ASTER data is [i.aster.toar](i.aster.toar.md). +For other satellites, [r.mapcalc](r.mapcalc.md) can be employed. + +**Reflection/radiance-at-sensor and surface reflectance** + +When radiance-at-sensor has been obtained, still the atmosphere +influences the signal as recorded at the sensor. This atmospheric +interaction with the sun energy reflected back into space by +ground/vegetation/soil needs to be corrected. The need of removing +atmospheric artifacts stems from the fact that the atmosphericic +conditions are changing over time. Hence, to gain comparability between +Earth surface images taken at different times, atmospheric need to be +removed converting at-sensor values which are top of atmosphere to +surface reflectance values. + +In GRASS GIS, there are two ways to apply atmospheric correction for +satellite imagery. A simple, less accurate way for Landsat is with +[i.landsat.toar](i.landsat.toar.md), using the DOS correction method. +The more accurate way is using [i.atcorr](i.atcorr.md) (which supports +many satellite sensors). The atmospherically corrected sensor data +represent surface +[reflectance](https://en.wikipedia.org/wiki/reflectance), which ranges +theoretically from 0% to 100%. Note that this level of data correction +is the proper level of correction to calculate vegetation indices. + +In GRASS GIS, image data are identical to [raster data](rasterintro.md). +However, a couple of commands are explicitly dedicated to image +processing. The geographic boundaries of the raster/imagery file are +described by the north, south, east, and west fields. These values +describe the lines which bound the map at its edges. These lines do NOT +pass through the center of the grid cells at the edge of the map, but +along the edge of the map itself. + +As a general rule in GRASS: + +1. Raster/imagery output maps have their bounds and resolution equal to + those of the current region. +2. Raster/imagery input maps are automatically cropped/padded and + rescaled (using nearest-neighbor resampling) to match the current + region. + +### Imagery import + +The module [r.in.gdal](r.in.gdal.md) offers a common interface for many +different raster and satellite image formats. Additionally, it also +offers options such as on-the-fly project creation or extension of the +default region to match the extent of the imported raster map. For +special cases, other import modules are available. Always the full map +is imported. Imagery data can be group (e.g. channel-wise) with +[i.group](i.group.md). + +For importing scanned maps, the user will need to create a x,y-project, +scan the map in the desired resolution and save it into an appropriate +raster format (e.g. tiff, jpeg, png, pbm) and then use +[r.in.gdal](r.in.gdal.md) to import it. Based on reference points the +scanned map can be rectified to obtain geocoded data. + +### Semantic label information + +Semantic labels are a description which can be stored as metadata. To +print available semantic labels relevant for multispectral satellite +data, use [i.band.library](i.band.library.md). +[r.semantic.label](r.semantic.label.md) allows assigning of these +satellite imagery band references as defined in +[i.band.library](i.band.library.md). Semantic labels are also used in +signature files of imagery classification tools. Therefore, signature +files of one imagery or raster group can be used to classify a different +group with identical semantic labels. + +
+ + +*New enhanced classification workflow involving semantic labels.* + +
+ +With [r.support](r.support.md) any sort of semantic label the user +wishes may be added (i.e., not only those registered in +*i.band.library*). Semantic labels are supported also by the +[temporal](temporalintro.md) GRASS modules. + +### Image processing operations + +GRASS raster/imagery map processing is always performed in the current +region settings (see [g.region](g.region.md)), i.e. the current region +extent and current raster resolution is used. If the resolution differs +from that of the input raster map(s), on-the-fly resampling is performed +(nearest neighbor resampling). If this is not desired, the input map(s) +has/have to be resampled beforehand with one of the dedicated modules. + +### Geocoding of imagery data + +GRASS is able to geocode raster and image data of various types: + +- unreferenced scanned maps by defining four corner points + ([i.group](i.group.md), [i.target](i.target.md), + [g.gui.gcp](g.gui.gcp.md), [i.rectify](i.rectify.md)) +- unreferenced satellite data from optical and Radar sensors by defining + a certain number of ground control points ([i.group](i.group.md), + [i.target](i.target.md), [g.gui.gcp](g.gui.gcp.md), + [i.rectify](i.rectify.md)) +- interactive graphical [Ground Control Point (GCP) + manager](wxGUI.gcp.md) +- orthophoto generation based on DEM: [i.ortho.photo](i.ortho.photo.md) +- digital handheld camera geocoding: modified procedure for + [i.ortho.photo](i.ortho.photo.md) + +### Visualizing (true) color composites + +To quickly combine the first three channels to a near natural color +image, the GRASS command [d.rgb](d.rgb.md) can be used or the graphical +GIS manager ([wxGUI](wxGUI.md)). It assigns each channel to a color +which is then mixed while displayed. With a bit more work of tuning the +grey scales of the channels, nearly perfect colors can be achieved. +Channel histograms can be shown with [d.histogram](d.histogram.md). + +### Calculation of vegetation indices + +An example for indices derived from multispectral data is the NDVI +(normalized difference vegetation index). To study the vegetation status +with NDVI, the Red and the Near Infrared channels (NIR) are taken as +used as input for simple map algebra in the GRASS command +[r.mapcalc](r.mapcalc.md) (`ndvi = 1.0 * (nir - red)/(nir + red)`). With +[r.colors](r.colors.md) an optimized "ndvi" color table can be assigned +afterward. Also other vegetation indices can be generated likewise. + +### Calibration of thermal channel + +The encoded digital numbers of a thermal infrared channel can be +transformed to degree Celsius (or other temperature units) which +represent the temperature of the observed land surface. This requires a +few algebraic steps with [r.mapcalc](r.mapcalc.md) which are outlined in +the literature to apply gain and bias values from the image metadata. + +### Image classification + +Single and multispectral data can be classified to user defined land +use/land cover classes. In case of a single channel, segmentation will +be used. GRASS supports the following methods: + +- Radiometric classification: + - Unsupervised classification ([i.cluster](i.cluster.md), + [i.maxlik](i.maxlik.md)) using the Maximum Likelihood classification + method + - Supervised classification ([i.gensig](i.gensig.md) or + [g.gui.iclass](g.gui.iclass.md), [i.maxlik](i.maxlik.md)) using the + Maximum Likelihood classification method +- Combined radiometric/geometric (segmentation based) classification: + - Supervised classification ([i.gensigset](i.gensigset.md), + [i.smap](i.smap.md)) +- Object-oriented classification: + - Unsupervised classification (segmentation based: + [i.segment](i.segment.md)) + +Kappa statistic can be calculated to validate the results +([r.kappa](r.kappa.md)). Covariance/correlation matrices can be +calculated with [r.covar](r.covar.md). + +Note - signatures generated for one scene are suitable for +classification of other scenes as long as they consist of same raster +bands (semantic labels match). This comes handy when classifying +multiple scenes from a single sensor taken in different areas or +different times. + +### Image fusion + +In case of using multispectral data, improvements of the resolution can +be gained by merging the panchromatic channel with color channels. GRASS +provides the HIS ([i.rgb.his](i.rgb.his.md), [i.his.rgb](i.his.rgb.md)) +and the Brovey and PCA transform ([i.pansharpen](i.pansharpen.md)) +methods. + +### Radiometric corrections + +Atmospheric effects can be removed with [i.atcorr](i.atcorr.md). +Correction for topographic/terrain effects is offered in +[i.topo.corr](i.topo.corr.md). Clouds in LANDSAT data can be identified +and removed with [i.landsat.acca](i.landsat.acca.md). Calibrated digital +numbers of LANDSAT and ASTER imagery may be converted to +top-of-atmosphere radiance or reflectance and temperature +([i.aster.toar](i.aster.toar.md), [i.landsat.toar](i.landsat.toar.md)). + +### Time series processing + +GRASS also offers support for time series processing +([r.series](r.series.md)). Statistics can be derived from a set of +coregistered input maps such as multitemporal satellite data. The common +univariate statistics and also linear regression can be calculated. + +### Evapotranspiration modeling + +In GRASS, several types of evapotranspiration (ET) modeling methods are +available: + +- Reference ET: Hargreaves ([i.evapo.mh](i.evapo.mh.md)), + Penman-Monteith ([i.evapo.pm](i.evapo.pm.md)); +- Potential ET: Priestley-Taylor ([i.evapo.pt](i.evapo.pt.md)); +- Actual ET: [i.evapo.time](i.evapo.time.md). + +Evaporative fraction: [i.eb.evapfr](i.eb.evapfr.md), +[i.eb.hsebal01](i.eb.hsebal01.md). + +### Energy balance + +Emissivity can be calculated with [i.emissivity](i.emissivity.md). +Several modules support the calculation of the energy balance: + +- Actual evapotranspiration for diurnal period + ([i.eb.eta](i.eb.eta.md)); +- Evaporative fraction and root zone soil moisture + ([i.eb.evapfr](i.eb.evapfr.md)); +- Sensible heat flux iteration ([i.eb.hsebal01](i.eb.hsebal01.md)); +- Net radiation approximation ([i.eb.netrad](i.eb.netrad.md)); +- Soil heat flux approximation + ([i.eb.soilheatflux](i.eb.soilheatflux.md)). + +### See also + +- GRASS GIS Wiki page: [Image + processing](https://grasswiki.osgeo.org/wiki/Image_processing) +- The GRASS 4 *[Image Processing + manual](https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf)* +- [Introduction into raster data processing](rasterintro.md) +- [Introduction into 3D raster data (voxel) + processing](raster3dintro.md) +- [Introduction into vector data processing](vectorintro.md) +- [Introduction into temporal data processing](temporalintro.md) +- [Database management](databaseintro.md) +- [Projections and spatial transformations](projectionintro.md) +- [Graphical User Interface](wxguiintro.md) diff --git a/lib/cairodriver/cairodriver.md b/lib/cairodriver/cairodriver.md new file mode 100644 index 00000000000..ba94b0982ef --- /dev/null +++ b/lib/cairodriver/cairodriver.md @@ -0,0 +1,162 @@ +*Cairo display driver* for bitmap or vector output using the Cairo +graphics library. + +## DESCRIPTION + +The Cairo driver generates PNG, BMP, PPM, PS, PDF or SVG images by GRASS +display commands, using the [Cairo graphics +library](https://www.cairographics.org/). The image format is selected +from the extension of the output file. The Cairo driver is used for +GRASS display commands by default if available, otherwise *[PNG +driver](pngdriver.md)* is used. + +## USAGE + +### Environment variables + +The Cairo driver can be enabled by setting **GRASS_RENDER_IMMEDIATE** +variable, eg. + +```bash +export GRASS_RENDER_IMMEDIATE=cairo +``` + +Several environment variables affect the operation of the Cairo driver: + +- **GRASS_RENDER_WIDTH=xxx** + the width of the image map (default is 640). +- **GRASS_RENDER_HEIGHT=yyy** + the height of the image map (default is 480). +- **GRASS_RENDER_BACKGROUNDCOLOR=RRGGBB** + specifies the background color to use in RGB notation (hex or R:G:B + values). Named colors are also supported. Default is **FFFFFF** + (white). +- **GRASS_RENDER_TRANSPARENT=\[TRUE\|FALSE\]** + sets transparent background on (TRUE) or off (FALSE, default). +- **GRASS_RENDER_ANTIALIAS** + can be *default*, *none*, *gray*, or *subpixel*, corresponding to + [cairo_antialias_t](https://www.cairographics.org/manual/cairo-cairo-t.html#cairo-antialias-t) +- **GRASS_RENDER_FILE=filename** + the name and format of the resulting image file, default is + `map.png`. + The image format is determined from the file extension. + Supported bitmap formats: + - **.png** - Portable Network Graphics (PNG) + - **.bmp** - Windows Bitmap (BMP, 32-bpp) (these are not readable by + some older viewers) + - **.ppm** - Portable Pixmap (PPM + PGM for alpha channel) + + Supported vector formats: + - **.pdf** - Portable Document Format (PDF) + - **.ps** - PostScript (PS) + - **.svg** - Scalable Vector Graphics (SVG) + + (Note: Some formats may not be available, depending on your platform + and the Cairo library that GRASS was built with.) +- **GRASS_RENDER_FILE_READ** + if `TRUE`, the Cairo driver will initialize the image from the + contents of GRASS_RENDER_FILE. + (*Note: This is only supported for bitmap formats*) +- **GRASS_RENDER_FILE_MAPPED** + if `TRUE`, the Cairo driver will map GRASS_RENDER_FILE as its + framebuffer, rather than using memory. + (*Note: This only works with BMP files.*) +- **GRASS_RENDER_CAIRO_SCREEN** + defines Cairo screen +- **GRASS_RENDER_CAIRO_VISUAL** + defines Cairo visual + +## EXAMPLES + +### PNG Example + +Example: using the driver to generate a PNG file (bash-syntax): + +```bash +export GRASS_RENDER_IMMEDIATE=cairo +export GRASS_RENDER_FILE=nc_spm.png +export GRASS_RENDER_WIDTH=800 +export GRASS_RENDER_HEIGHT=800 +export GRASS_RENDER_FILE_READ=TRUE + +g.region raster=elevation +d.rast map=elevation +d.vect map=streams width=1 color=blue fcolor=aqua type=area,line +d.vect map=roadsmajor width=2 +``` + +### PDF Examples + +Example: using the driver to generate a PDF vector file with a vector +map (bash-syntax): + +```bash +export GRASS_RENDER_IMMEDIATE=cairo +export GRASS_RENDER_FILE=nc_spm.pdf +export GRASS_RENDER_WIDTH=800 +export GRASS_RENDER_HEIGHT=800 + +g.region vector=roadsmajor +# activate vector font +d.font Vera +d.vect map=roadsmajor layer=1 display=shape attrcolumn=ROAD_NAME lcolor=0:90:255 +``` + +Example: using the driver to generate a PDF raster file with a raster +map (bash-syntax): + +```bash +export GRASS_RENDER_IMMEDIATE=cairo +export GRASS_RENDER_FILE=nc_spm.pdf +export GRASS_RENDER_WIDTH=800 +export GRASS_RENDER_HEIGHT=800 + +g.region raster=elevation +d.rast map=elevation +``` + +### SVG Example + +Example: using the driver to generate a SVG vector file with a vector +map (bash-syntax): + +```bash +export GRASS_RENDER_IMMEDIATE=cairo +export GRASS_RENDER_FILE=vectormap.svg + +g.region vector=roadsmajor +d.vect map=roadsmajor -c +``` + +## NOTES + +The driver is still in development. Enable it by specifying +`--with-cairo` when configuring GRASS. This requires a reasonably recent +version of the Cairo libraries and a working `pkg-config`. + +Antialiasing is enabled by default for bitmap formats. There is +currently no way of disabling this. + +The resolution of the output images is defined by current region +extents. Use `g.region -p` to get the number of rows and cols and use +the environment variables to set the image size. If you would like a +larger image, multiply both rows and cols by the same whole number to +preserve the aspect ratio. + +Cairo supports true vector format output whenever possible. However, if +the selected format doesn't support a necessary feature, Cairo may fall +back on rendering a bitmap representation of the image wrapped in the +selected vector format. + +## SEE ALSO + +*[PNG driver](pngdriver.md), [PS driver](psdriver.md), [HTML +driver](htmldriver.md), [variables](variables.md)* + +*[d.rast](d.rast.md), [d.vect](d.vect.md), [d.mon](d.mon.md), +[d.erase](d.erase.md), [d.redraw](d.redraw.md)* + +## AUTHOR + +Lars Ahlzen \<*lars (at) ahlzen.com*\> +and the GRASS Development Team. diff --git a/lib/db/dbmi_base/test/test.dbmi_base.lib.md b/lib/db/dbmi_base/test/test.dbmi_base.lib.md new file mode 100644 index 00000000000..6b3ec61e94c --- /dev/null +++ b/lib/db/dbmi_base/test/test.dbmi_base.lib.md @@ -0,0 +1,2 @@ +Unit and integration tests for the dbmi base library. Only basic table +and column tests are currently implemented. diff --git a/lib/db/sqlp/sql.md b/lib/db/sqlp/sql.md new file mode 100644 index 00000000000..d1b4cf69a2f --- /dev/null +++ b/lib/db/sqlp/sql.md @@ -0,0 +1,214 @@ +Vector points, lines and areas usually have attribute data that are +stored in DBMS. The attributes are linked to each vector object using a +category number (attribute ID, usually the "cat" integer column). The +category numbers are stored both in the vector geometry and the +attribute table. + +GRASS GIS supports various RDBMS ([Relational database management +system](https://en.wikipedia.org/wiki/Relational_database_management_system)) +and embedded databases. SQL ([Structured Query +Language](https://en.wikipedia.org/wiki/Sql)) queries are directly +passed to the underlying database system. The set of supported SQL +commands depends on the RDMBS and database driver selected. + +## Database drivers + +The default database driver used by GRASS GIS 8 is SQLite. GRASS GIS +handles multiattribute vector data by default. The *db.\** set of +commands provides basic SQL support for attribute management, while the +*v.db.\** set of commands operates on vector maps. + +Note: The list of available database drivers can vary in various binary +distributions of GRASS GIS: + +| | | | +|---------------------------|------------------------------------------------------------|---------------------------------------------| +| [sqlite](grass-sqlite.md) | Data storage in SQLite database files (default DB backend) | | +| [dbf](grass-dbf.md) | Data storage in DBF files | | +| [pg](grass-pg.md) | Data storage in PostgreSQL RDBMS | | +| [mysql](grass-mysql.md) | Data storage in MySQL RDBMS | | +| [odbc](grass-odbc.md) | Data storage via UnixODBC (PostgreSQL, Oracle, etc.) | | +| [ogr](grass-ogr.md) | Data storage in OGR files | [https://gdal.org/](https://gdal.org) | + +## NOTES + +### Database table name restrictions + +- No dots are allowed as SQL does not support '.' (dots) in table names. + +- Supported table name characters are only: + + ```bash + [A-Za-z][A-Za-z0-9_]* + ``` + +- A table name must start with a character, not a number. + +- Text-string matching requires the text part to be 'single quoted'. + When run from the command line multiple queries should be contained in + "double quotes". e.g. + + ```bash + d.vect map where="individual='juvenile' and area='beach'" + ``` + +- Attempts to use a reserved SQL word (depends on database backend) as + column or table name will cause a "SQL syntax error". + +- An error message such as "`dbmi: Protocol error`" either indicates an + invalid column name or an unsupported column type (then the GRASS SQL + parser needs to be extended). + +- DBF column names are limited to 10 characters (DBF API definition). + +### Database table column types + +The supported types of columns depend on the database backend. However, +all backends should support VARCHAR, INT, DOUBLE PRECISION and DATE. + +## EXAMPLES + +### Display of vector feature selected by attribute query + +Display all vector points except for *LAMAR* valley and *extensive +trapping* (brackets are superfluous in this example): + +```bash +g.region vector=schools_wake -p +d.mon wx0 +d.vect roadsmajor + +# all schools +d.vect schools_wake fcol=black icon=basic/diamond col=white size=13 + +# numerical selection: show schools with capacity of above 1000 kids: +d.vect schools_wake fcol=blue icon=basic/diamond col=white size=13 \ + where="CAPACITYTO > 1000" + +# string selection: all schools outside of Raleigh +# along with higher level schools in Raleigh +d.vect schools_wake fcol=red icon=basic/diamond col=white size=13 \ + where="ADDRCITY <> 'Raleigh' OR (ADDRCITY = 'Raleigh' AND GLEVEL = 'H')" +``` + +Select all attributes from table where *CORECAPACI* column values are +smaller than 200 (children): + +```bash +# must be run from the mapset which contains the table +echo "SELECT * FROM schools_wake WHERE CORECAPACI < 200" | db.select input=- +``` + +Example of subquery expressions from a list (not supported for DBF +driver): + +```bash +v.db.select schools_wake where="ADDRCITY IN ('Apex', 'Wendell')" +``` + +### Example of pattern matching + +```bash +# field contains string: +# for DBF driver: +v.extract schools_wake out=elementary_schools where="NAMELONG LIKE 'ELEM'" +# for SQLite driver: +v.extract schools_wake out=rivers_noce where="DES LIKE '%NOCE%'" +v.extract schools_wake out=elementary_schools where="NAMELONG LIKE '%ELEM%'" + +# match exactly number of characters (here: 2), does not work for DBF driver: +v.db.select mysites where="id LIKE 'P__'" + +#define wildcard: +v.db.select mysites where="id LIKE 'P%'" +``` + +### Example of null handling + +```bash +v.db.addcolumn map=roads col="nulltest int" +v.db.update map=roads col=nulltest value=1 where="cat > 2" +d.vect roads where="nulltest is null" +v.db.update map=roads col=nulltest value=2 where="cat <= 2" +``` + +### Update of attributes + +Examples of complex expressions in updates (using `v.db.*` modules): + +```bash +v.db.addcolumn map=roads column="exprtest double precision" +v.db.update map=roads column=exprtest value="cat/nulltest" +v.db.update map=roads column=exprtest value="cat/nulltest+cat" where="cat=1" + +# using data from another column +v.db.update map=roads column=exprtest qcolumn="(cat*100.)/SHAPE_LEN." +``` + +Examples of more complex expressions in updates (using `db.*` modules): + +```bash +echo "UPDATE roads SET exprtest=null" +echo "UPDATE roads SET exprtest=cat/2" | db.execute +echo "UPDATE roads SET exprtest=cat/2+cat/3" | db.execute +echo "UPDATE roads SET exprtest=NULL WHERE cat>2" | db.execute +echo "UPDATE roads SET exprtest=cat/3*(cat+1) WHERE exprtest IS NULL" | db.execute" +``` + +Instead of creating and updating new columns with an expression, you can +use the expression directly in a command: + +```bash +d.vect roads where="(cat/3*(cat+1))>8" +d.vect roads where="cat>exprtest" +``` + +### Example of changing a SQL type (type casting) + +*Note: not supported for [DBF driver](grass-dbf.md).* + +North Carolina data set: convert string column to double precision: + +```bash +# first copy map into current mapset +g.copy vect=geodetic_pts,mygeodetic_pts +v.db.addcolumn mygeodetic_pts col="zval double precision" + +# the 'z_value' col contains 'N/A' strings, not to be converted +v.db.update mygeodetic_pts col=zval \ + qcol="CAST(z_value AS double precision)" \ + where="z_value <> 'N/A'" +``` + +### Example of concatenation of fields + +*Note: not supported for [DBF driver](grass-dbf.md).* + +```bash +v.db.update vectormap column=column3 qcolumn="column1 || column2" +``` + +### Example of conditions + +Conditions (like if statements) are usually written as CASE statement in +SQL: + +```bash +v.db.update vectormap column=species qcolumn="CASE WHEN col1 >= 12 THEN cat else NULL end" + +# a more complex example with nested conditions +v.db.update vectormap column=species qcolumn="CASE WHEN col1 >= 1 THEN cat WHEN row = 13 then 0 ELSE NULL end" +``` + +## SEE ALSO + +*[db.connect](db.connect.md), [db.select](db.select.md), +[db.execute](db.execute.md), [v.db.connect](v.db.connect.md), +[v.db.select](v.db.select.md), [v.db.update](v.db.update.md)* + +[Database management in GRASS GIS](databaseintro.md), [Help pages for +database modules](database.md) + +## AUTHOR + +Radim Blazek diff --git a/lib/gmath/test/test.gmath.lib.md b/lib/gmath/test/test.gmath.lib.md new file mode 100644 index 00000000000..37c1062745e --- /dev/null +++ b/lib/gmath/test/test.gmath.lib.md @@ -0,0 +1 @@ +Take a look at the module command line help for more information. diff --git a/lib/gpde/test/test.gpde.lib.md b/lib/gpde/test/test.gpde.lib.md new file mode 100644 index 00000000000..3f58ac55faa --- /dev/null +++ b/lib/gpde/test/test.gpde.lib.md @@ -0,0 +1,9 @@ +## DESCRIPTION + +Test suite. + +## SEE ALSO + +## AUTHOR + +Soeren Gebbert diff --git a/lib/htmldriver/htmldriver.md b/lib/htmldriver/htmldriver.md new file mode 100644 index 00000000000..51aedb145b9 --- /dev/null +++ b/lib/htmldriver/htmldriver.md @@ -0,0 +1,162 @@ +*HTML display driver* to create HTML image maps. + +## DESCRIPTION + +The HTML driver allows the generation of HTML image maps for area vector +data. HTML image maps are used in conjunction with images to provide +unique URL targets for different portions of an image. The HTML driver +can create both client-side image maps embedded into HTML files, or +server-side image maps used by web server software. + +Polygons can at most have 100 vertices (this limit imposed by HTML image +map formats, see **GRASS_RENDER_HTMLMAXPOINTS** below.) The driver will +attempt to trim polygons that have more that 100 vertices by removing +vertices with the least amount of angle to the next vertice. Also, any +polygon that is entirely bounded by another polygon will be discarded. + +Text written to the driver before polygons are used as the HREF tag for +all subsequent polygons written. All polygons that exist in a vector map +will have the same HREF tag. + +The only GRASS display commands that should be used with this driver +are: + +- *[d.text](d.text.md)* - pass href information for resulting image + maps. +- *[d.vect](d.vect.md)* - draw polygons from a vector map. + +## USAGE + +### Environment variables + +The HTML driver can be enabled by setting **GRASS_RENDER_IMMEDIATE** +variable, eg. + +```bash +export GRASS_RENDER_IMMEDIATE=html +``` + +Several environment variables affect the operation of the HTML driver: + +- **GRASS_RENDER_WIDTH=xxx** + the width of the image map (default is 640). +- **GRASS_RENDER_HEIGHT=yyy** + the height of the image map (default is 480). +- **GRASS_RENDER_HTMLTYPE=type** + type of image map to create (default is CLIENT): + **`CLIENT`**    Netscape/IE client-side image map (NAME="map"). + **`APACHE`**    Apache/NCSA server-side image map. + **`RAW`**         Raw url and polygon vertices (*url  x1  y1  x2  y2 + .....*), suitable for conversion to CERN server format, or any other + format with user supplied conversion program. +- **GRASS_RENDER_FILE=filename** + specifies the resulting file to store the html image map, default is + `htmlmap`. Files without absolute path names are written in the + current directory where the driver was started. + *Any existing file of the same name is overwritten without warning.* +- **GRASS_RENDER_HTMLMINDIST=n** + specifies the minimum distance in pixels that a point must change from + the previous point to keep in the list of vertices for a polygon. The + default is `2`, which means that a point's x and y difference from the + previous point must change by a number of pixels greater than this + value. This parameter helps to eliminate closely spaced points. +- **GRASS_RENDER_HTMLMINBBOX=n** + specifies the minimum bounding box dimensions to record a polygon as a + clickable area. The default is `2`, which means that a polygon with a + bounding box of less than this value is not included. This parameter + helps to eliminate polygons than are a point or line. +- **GRASS_RENDER_HTMLMAXPOINTS=n** + specifies the maximum number of vertices included in a polygon's + clickable area. The default is `99`. Some browsers can only + accommodate polygons of 100 vertices or less. The HTMLMAP driver + automatically ensures that a polygon is closed by making the last + point the same as the first point. + +### Example + +Start up the driver + +```bash +g.region vector=zipcodes_wake +d.mon start=html +``` + +Display text strings (HREF's) and polygons + +```bash +echo "https://en.wikipedia.org/wiki/Raleigh,_North_Carolina" | d.text +d.vect map=zipcodes_wake where="ZIPNAME = 'RALEIGH'" +echo "https://en.wikipedia.org/wiki/Cary,_North_Carolina" | d.text +d.vect map=zipcodes_wake where="ZIPNAME = 'CARY'" fill_color=180:200:210 +``` + +Stop the driver once all polygon have been displayed. This will create a +file named 'htmlmap' in your current directory: + +```bash +d.mon stop=html +``` + +You will also want to create an image for your image map. Use the PNG +driver and other utilities to create .gif or .jpg files. *The following +example is somewhat out of date and refers to options available in GRASS +5.* + +```bash +# using previous GRASS_RENDER_WIDTH & GRASS_RENDER_HEIGHT +d.mon start=png +d.rast map=terrain +d.vect map=area51 fillcolor=white linecolor=blue +d.vect map=roswell fillcolor=yellow linecolor=blue +d.vect map=states color=green +d.vect map=roads color=black +d.mon stop=png + + +# make the region the same as the newly created cell for ppm export +g.region save=saved.reg +g.region raster=D_cell +r.out.ppm -q input=D_cell output=alien.ppm + +# use the netpbm utilities to create a gif (quantize if needed) +ppmquant 128 alien.gif + +# assemble some html with the image and the image map +echo '' >alien.html +cat htmlmap >>alien.html +echo '' >>alien.html + +# don't forget to reset your region +g.region region=saved.reg + +# take a look and test it out +netscape file:`pwd`/alien.html & +``` + +## NOTES + +HTML was adapted from the CELL driver in GRASS 4.3. Point-in-polygon +test code was lifted from Randolph Franklin's web page, see + +- +- + +If you create an HTML file with two or more images and image maps, you +will need to edit the map names. The HTML driver creates its map with +the name `map`. A small sed script can easily change the map name: + +```bash +sed -e 's/NAME="map"/NAME="foomap"/' < htmlmap > foomap.html +``` + +## SEE ALSO + +*[Cairo driver](cairodriver.md), [PNG driver](pngdriver.md), [HTML +driver](htmldriver.md), [variables](variables.md)* + +*[d.rast](d.rast.md), [d.vect](d.vect.md), [d.mon](d.mon.md), +[d.erase](d.erase.md), [d.redraw](d.redraw.md)* + +## AUTHOR + +Glynn Clements diff --git a/lib/init/grass.md b/lib/init/grass.md new file mode 100644 index 00000000000..aec9f176c3c --- /dev/null +++ b/lib/init/grass.md @@ -0,0 +1,471 @@ +## SYNOPSIS + +**grass** \[**-h** \| **-help** \| **--help**\] \[**-v** \| +**--version**\] \| \[**-c** \| **-c geofile** \| **-c +EPSG:code\[:datum_trans\]**\] \| **-e** \| **-f** \| \[**--text** \| +**--gtext** \| **--gui**\] \| **--config** \| \[**--tmp-project** \| +**--tmp-mapset**\] \[\[\[**\/**\]**\/**\] +**\**\] \[**--exec EXECUTABLE**\] + +### Flags + +**-h** \| **-help** \| **--help** +Prints a brief usage message and exits + +**-v** \| **--version** +Prints the version of GRASS and exits + +**-c XY** +Creates new GRASS project (location) without coordinate reference system +in specified GISDBASE + +**-c geofile** +Creates new GRASS project in specified GISDBASE with coordinate +reference system based on georeferenced file + +**-c EPSG:code** +Creates new GRASS project in specified GISDBASE with coordinate +reference system defined by EPSG code + +**-c EPSG:code:datum_trans** +Creates new GRASS project in specified GISDBASE with coordinate +reference system defined by EPSG code and datum transform parameters + +**-e** +Exit after creation of project or mapset. Only with **-c** flag + +**-f** +Forces removal of .gislock if exists (use with care!). Only with --text +flag + +**--text** +Indicates that Text-based User Interface should be used (skip welcome +screen) + +**--gtext** +Indicates that Text-based User Interface should be used (show welcome +screen) + +**--gui** +Indicates that Graphical User Interface (*[wxGUI](wxGUI.md)*) should be +used + +**--config** +Prints GRASS configuration parameters (options: arch, build, compiler, +date, path, python_path, revision, svn_revision, version) + +**--exec EXECUTABLE** +Execute GRASS module or script. The provided executable will be executed +in a GRASS GIS non-interactive session. + +**--tmp-project** +Run using a temporary project which is created based on the given +coordinate reference system and deleted at the end of the execution (use +with the --exec flag). The active mapset will be the PERMANENT mapset. + +**--tmp-mapset** +Run using a temporary mapset which is created in the specified project +and deleted at the end of the execution (use with the --exec flag). + +### Parameters + +**GISDBASE** +Initial database directory which should be a fully qualified path (e.g., +`/usr/local/share/grassdata`) + +**PROJECT** +Initial project directory which is a subdirectory of GISDBASE (project +was previously called location) + +**MAPSET** +Initial mapset directory which is a subdirectory of PROJECT + +*Note*: These parameters must be specified in one of the following ways: + +```bash + MAPSET + PROJECT/MAPSET + GISDBASE/PROJECT/MAPSET +``` + +## DESCRIPTION + +This command is used to launch GRASS GIS. It will parse the command line +arguments and then initialize GRASS for the user. Since GRASS modules +require a specific environment, this program must be called before any +other GRASS module can run. The command line arguments are optional and +provide the user with a method to indicate the desired user interface, +as well as the desired mapset to work on. + +The startup program will remember both the desired user interface and +mapset. Thus, the next time the user runs GRASS, typing *grass* (without +any options) will start GRASS with the previous settings for the user +interface and mapset selected. + +If you specify a graphical user interface (**--gui**) the *grass* +program will try to verify that the system you specified exists and that +you can access it successfully. If any of these checks fail then *grass* +will automatically switch back to the text user interface mode. + +### Running non-interactive jobs + +The **--exec** flag can run an executable on path, GRASS module, or a +script. All are executed as a subprocess and any additional arguments +are passed to it. A script needs to be specified by full or relative +path and on unix-likes systems, the script file must have its executable +bit set. Calling the interpreter (e.g., `python`) and providing the +script as a parameter is possible, too. When it is finished GRASS will +automatically exit using the return code given by the subprocess. +Although the execution itself is non-interactive (no GUI or shell), the +subprocess itself can be interactive if that is what the user requires. + +### Config flag + +The flag **--config option** prints GRASS GIS configuration and version +parameters, with the options: + +- **arch**: system architecture (e.g., `x86_64-pc-linux-gnu`) +- **build**: (e.g., + `./configure --with-cxx --enable-largefile --with-proj [...]`) +- **compiler**: (e.g., `gcc`) +- **date**: (e.g., `2024-04-10T11:44:54+00:00`) +- **path**: (e.g., `/usr/lib64/grass`) +- **python_path**: (e.g., `/usr/lib64/grass/etc/python`) +- **revision**: (e.g., `745ee7ec9`) +- **svn_revision**: (e.g., `062bffc8`) +- **version**: (e.g., `8.4.0`) + +## SAMPLE DATA + +The GRASS GIS project provides several free sample geospatial datasets +as ready-to-use projects. They are available to download at +. The "North Carolina +data set" is a modern package of geospatial data from North Carolina +(USA), and it includes raster, vector, LiDAR and satellite data. This is +the most extensively used data set in the documentation and the examples +throughout the user manual pages are based upon it. + +## ENVIRONMENT VARIABLES + +A number of environment variables are available at GRASS startup to +assist with automation and customization. Most users will not need to +bother with these. + +In addition to these shell environment variables GRASS maintains a +number of GIS environment variables in the `$HOME/.grass8/rc` file. User +changes to this file will be read during the next startup of GRASS. If +this file becomes corrupted the user may edit it by hand or remove it to +start afresh. See the list of *[implemented GRASS +variables](variables.md)* for more information. The rest of this help +page will only consider shell environment variables. + +Note that you will need to set these variables using the appropriate +method required for the UNIX shell that you use (e.g. in a Bash shell +you must `export` the variables for them to propagate). + +### User Interface Environment Variable + +The *grass* program will check for the existence of an environment +variable called GRASS_GUI which indicates the type of user interface for +GRASS to use. If this variable is not set when *grass* is run, then it +will be created and then saved in the `$HOME/.grass8/rc` file for the +next time GRASS is run. It can be set to `text`, `gtext` or `gui`. + +There is an order of precedence in the way *grass* determines the user +interface to use. The following is the hierarchy from highest precedence +to lowest. + +1. Command line argument +2. Environment variable GRASS_GUI +3. Value set in `$HOME/.grass8/rc` (GUI) +4. Default value - `gui` + +### Python Environment Variables + +If you choose to use *[wxGUI](wxGUI.md)* interface, then the +GRASS_PYTHON environment variable can be used to override your system +default `python` command. + +Suppose for example your system has Python 3.6 installed and you install +a personal version of the Python 3.8 binaries under `$HOME/bin`. You can +use the above variables to have GRASS use the Python 3.8 binaries +instead. + +```bash + GRASS_PYTHON=python3.8 +``` + +### Addon Path to Extra User Scripts + +This environment variable allows the user to extend the GRASS program +search paths to include locally developed/installed GRASS modules or +user scripts. + +```bash + GRASS_ADDON_PATH=/usr/mytools + GRASS_ADDON_PATH=/usr/mytools:/usr/local/othertools +``` + +In this example above path(s) would be added to the standard GRASS path +environment. + +### Addon Base for Extra Local GRASS Addon Modules + +This environment variable allows the user to extend the GRASS program +search paths to include locally installed (see +*[g.extension](g.extension.md)* for details) [GRASS +Addon](https://grasswiki.osgeo.org/wiki/GRASS_AddOns) modules which are +not distributed with the standard GRASS release. + +```bash + GRASS_ADDON_BASE=/usr/grass-addons +``` + +In this example above path would be added to the standard GRASS path +environment. + +If not defined by user, this variable is set by GRASS startup program to +`$HOME/.grass8/addons` on GNU/Linux and +`%APPDATA%\Roaming\GRASS8\addons` on MS Windows. + +### HTML Browser Variable + +The GRASS_HTML_BROWSER environment variable allows the user to set the +HTML web browser to use for displaying help pages. + +## EXAMPLES + +The following are some examples of how you could start GRASS + +**grass** +Start GRASS using the default user interface. The user will be prompted +to choose the appropriate project and mapset. + +**grass --gui** +Start GRASS using the graphical user interface. The user will be +prompted to choose the appropriate project and mapset. + +**grass --text** +Start GRASS using the text-based user interface. Appropriate project and +mapset must be set by environmental variables (see examples below) +otherwise taken from the last GRASS session. + +**grass --gtext** +Start GRASS using the text-based user interface. The user will be +prompted to choose the appropriate project and mapset. + +**grass $HOME/grassdata/spearfish70/user1** +Start GRASS using the default user interface and automatically launch +into the given mapset, bypassing the mapset selection menu. + +**grass --gui -** +Start GRASS using the graphical user interface and try to obtain the +project and mapset from environment variables. + +**grass -c EPSG:4326 $HOME/grassdata/myproject** +Creates a new GRASS project with EPSG code 4326 (latitude-longitude, +WGS84) in the specified GISDBASE + +**grass -c EPSG:5514:3 $HOME/grassdata/myproject** +Creates a new GRASS project with EPSG code 5514 (S-JTSK / Krovak East +North - SJTSK) with datum transformation parameters used in Czech +Republic in the specified GISDBASE + +**grass -c XY $HOME/grassdata/gnomonic --exec g.proj -c proj4='+proj=gnom +lat_0=90 +lon_0=-50'** +Creates a new GRASS project from PROJ definition string (here: +[gnomonic](https://proj4.org/operations/projections/gnom.html)) in the +specified GISDBASE + +**grass -c myvector.shp $HOME/grassdata/myproject** +Creates a new GRASS project based on georeferenced Shapefile + +**grass -c myraster.tif $HOME/grassdata/myproject** +Creates a new GRASS project based on georeferenced GeoTIFF file + +### Batch jobs with the exec interface + +Creating a new project based on a geodata file's projection (**-c**) and +exit (**-e**) immediately: + +```bash +grass -c elevation.tiff -e /path/to/grassdata/test1/ +``` + +Linking external raster data to PERMANENT Mapset: + +```bash +grass /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins +grass /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation +``` + +Get statistics for one raster map: + +```bash +grass /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation +``` + +Compare the rasters visually: + +```bash +grass /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins +``` + +#### Execution of shell and Python scripts instead of single commands + +A sequence of commands can be bundled in a script and executed using the +exec interface. + +**Shell script example:** the command to execute a shell script might +be: + +```bash +grass /path/to/grassdata/test1/PERMANENT/ --exec sh test.sh +``` + +A very simple bash script ("test.sh") may look like this: + +```bash +#!/bin/bash + +g.region -p +g.list type=raster +r.info elevation +``` + +**Python script example:** the command to execute a Python script might +be: + +```bash +grass /path/to/grassdata/test1/PERMANENT/ --exec python test.py +``` + +A very simple Python script ("test.py") may look like this: + +```bash +#!/usr/bin/env python3 + +# import GRASS Python bindings (see also pygrass) +import grass.script as gs + +gs.message('Current GRASS GIS environment:') +print(gs.gisenv()) + +gs.message('Available raster maps:') +for raster in gs.list_strings(type='raster'): + print(raster) + +gs.message('Available vector maps:') +for vector in gs.list_strings(type='vector'): + print(vector) +``` + +#### Using temporary project + +Creating a new temporary project based on a georeferenced file's +coordinate reference system (CRS) and simultaneously starting +computation in a shell script: + +```bash +grass --tmp-project elevation.tiff --exec test.sh +``` + +The same, but using an EPSG code and a Python script: + +```bash +grass --tmp-project EPSG:3358 --exec test.py +``` + +Finally, for special cases, we can create an XY project without any CRS: + +```bash +grass --tmp-project XY --exec test.py +``` + +Temporary project is automatically deleted after computation, so the +script is expected to export, link or otherwise preserve the output data +before ending. + +A single command can be also executed, e.g. to examine properties of the +temporary project: + +```bash +grass --tmp-project EPSG:3358 --exec g.proj -p +``` + +A temporary XY project with single command is useful, e.g. to show help +text of a module: + +```bash +grass --tmp-project XY --exec r.neighbors --help +``` + +#### Using temporary mapset + +A single command can be executed, e.g., to examine properties of a +project (here using the NC SPM sample dataset): + +```bash +grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec g.proj -p +``` + +Computation in a Python script can be executed in the same way: + +```bash +grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py +``` + +Additional parameters are just passed to the script, so we can run the +script with different sets of parameters (here 5, 8 and 3, 9) in +different temporary mapsets which is good for parallel processing. + +```bash +grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py 5 8 +grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py 3 9 +``` + +The same applies to Bash scripts (and other scripts supported on you +platform): + +```bash +grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.sh 5 8 +``` + +The temporary mapset is automatically deleted after computation, so the +script is expected to export, link or otherwise preserve the output data +before ending. + +#### Troubleshooting + +Importantly, to avoid an `"[Errno 8] Exec format error"` there must be a +[shebang](https://en.wikipedia.org/wiki/Shebang_%28Unix%29) line at the +top of the script (like `#!/bin/sh`, `#!/bin/bash`, or +`#!/usr/bin/env python3`) indicating which interpreter to be used for +the script. The script file must have its executable bit set. + +## CAVEAT + +If you start GRASS using the *[wxGUI](wxGUI.md)* interface you must have +a `python` command in your $PATH variable. That is, the command must be +named `python` and not something like `python3.6`. Rarely some Python +installations do not create a `python` command. In these cases you can +override `python` by GRASS_PYTHON environmental variable. + +Furthermore, if you have more than one version of Python installed, make +sure that the version you want to use with GRASS is set by GRASS_PYTHON +environmental variable. + +## SEE ALSO + +List of [GRASS environment variables](variables.md) + +[GRASS GIS Web site](https://grass.osgeo.org) +[GRASS GIS User Wiki](https://grasswiki.osgeo.org/wiki/) +[GRASS GIS Bug Tracker](https://github.com/OSGeo/grass/issues) +[GRASS GIS 8 Programmer's Manual](https://grass.osgeo.org/programming8/) + +## AUTHORS (of this page) + +Justin Hickey +Markus Neteler +Hamish Bowman +Martin Landa, Czech Technical University in Prague, Czech Republic diff --git a/lib/init/helptext.md b/lib/init/helptext.md new file mode 100644 index 00000000000..654834e632a --- /dev/null +++ b/lib/init/helptext.md @@ -0,0 +1,84 @@ +When [launching](grass.md) GRASS GIS for the first time, you will open a +**default project** "world_latlog_wgs84" where you can find a map layer +called "country_boundaries" showing a world map in the WGS84 coordinate +system. + +![\[GRASS GIS after first startup\]](grass_start.png) + +The main component of the Data tab is the *Data Catalog* which shows the +GRASS GIS hierarchical structure consisting of database ![\[GRASS +Database\]](grassdb.png), project ![\[project\]](location.png) and +mapset ![\[mapset\]](mapset.png). + +![\[GRASS Database\]](grassdb.png) **GRASS database** (directory with projects) +Running GRASS GIS for the first time, a folder named "grassdata" is +automatically created. Depending on your operating system, you can find +it in your $HOME directory (\*nix) or My Documents (MS Windows). + +![\[project\]](location.png) **project** (previously called location) +A project is defined by its coordinate reference system (CRS). In the +case of the default project, it is a geographic coordinate reference +system WGS84 (EPSG:4326). If you have data in another CRS than WGS84, +you should create a new project corresponding to your system. + +![\[mapset\]](mapset.png) **mapset** (a subproject) +Each project can have many mapsets for managing different aspects of a +project or project's subregions. When creating a new project, GRASS GIS +automatically creates a special mapset called PERMANENT where the core +data for the project can be stored. + +For more info about data hierarchy, see [GRASS GIS +Database](grass_database.md) page. + +## GRASS started in the default project, now what? + +First, if you would like to get to know GRASS better before importing +your own data, please download provided samples such as the "North +Carolina" dataset. You can simply reach them through "Download sample +project to current database" management icon ![\[Download +project\]](location-download.png). + +To work with your own data, you typically want to first create a new +project with a [coordinate reference system +(CRS)](https://en.wikipedia.org/wiki/Spatial_reference_system) suitable +for your study area or one that matches your data's CRS. The Project +Wizard ![\[Add project\]](location-add.png) will help you with that by +guiding you through a series of dialogs to browse and select predefined +projections (also via EPSG code) or to define individual projections. + +### Creating a New project with the Project Wizard + +If you know the CRS of your data or study area, you can fill [EPSG +code](https://spatialreference.org/) or description and Project Wizard +finds appropriate CRS from a predefined list of projections. If you do +not know CRS of you data, you can read it from your georeferenced data +file (e.g. shapefile or GeoTiff file with the related metadata properly +included). + +### Importing data + +After creating a new project, you are ready to import your data. You can +use simple raster or vector data import ![\[Raster +import\]](raster-import.png), ![\[Vector import\]](vector-import.png) or +a variety of more specialized tools. If the data's CRS does not match +your project's CRS, data will be automatically reprojected. After import +your raster or vector data are added as a layer to Map Display. To +change layer properties, go to Display tab. To analyze your data, search +for a tool in the Modules tab. + +## Text-based startup and project creation + +GRASS GIS can be run entirely without using the graphical user +interface. See [examples](grass.md) of running GRASS GIS from a command +line. + +## See also + +*[GRASS GIS Reference Manual](index.md) +[GRASS GIS startup program manual page](grass.md) +[GRASS GIS tutorials and books](https://grass.osgeo.org/learn/)* + +[List of EPSG codes](https://spatialreference.org/) (Database of +worldwide coordinate systems), [CRS Explorer - PROJ +codes](https://crs-explorer.proj.org/), and [EPSG Geodetic Parameter +Dataset](https://epsg.org/) diff --git a/lib/init/variables.md b/lib/init/variables.md new file mode 100644 index 00000000000..965396e0a56 --- /dev/null +++ b/lib/init/variables.md @@ -0,0 +1,571 @@ +A variable in scripting is a symbolic name that holds data which can be +used and modified during script execution. Variables allow scripts to +store and manipulate values dynamically, making them more flexible and +reusable. In GRASS GIS, there are two types of variables: + +- [shell environment](#setting-shell-environment-variables) variables, +- [GRASS gisenv](#setting-grass-gisenv-variables) variables. + +There are a number of *shell* environment variable groups: + +- [variables for + rendering](#list-of-selected-grass-environment-variables-for-rendering) +- [variables for internal + use](#list-of-selected-internal-grass-environment-variables) + +*Note:* Any setting which needs to be modifiable by a GRASS module (e.g. +MONITOR by *[d.mon](d.mon.md)*) has to be a GRASS gisenv variable. + +## Setting shell environment variables + +Setting shell environment variables depends on the shell being used: + +Bash: + +```bash +export VARIABLE=value +``` + +Csh: + +```bash +setenv VARIABLE value +``` + +Cmd.exe (Windows): + +```bash +set VARIABLE=value +``` + +To set up shell environment variables permanently: + +- To get personal BASH shell definitions (aliases, color listing option, + ...) into GRASS, store them in: + `$HOME/.grass8/bashrc` +- To get personal CSH shell definitions (aliases, color listing option, + ...) into GRASS, store them in: + `$HOME/.grass8/cshrc` + +## Setting GRASS gisenv variables + +Use *[g.gisenv](g.gisenv.md)* within GRASS. This permanently predefines +GRASS variables in the `$HOME/.grass8/rc` file (Linux, Mac, BSD, ...) or +in the `%APPDATA%\Roaming\GRASS8\rc` file (Windows) after the current +GRASS session is closed. + +Usage: + +```bash +g.gisenv set="VARIABLE=VALUE" +``` + +It looks unusual with two equals signs, but *g.gisenv* serves dual duty +for getting and setting GRASS variables. + +If the user just specifies a variable name, it defaults to **get** mode. +For example: + +```bash +g.gisenv MAPSET +PERMANENT +``` + +## List of selected (GRASS related) shell environment variables + +> \[ To be set from the terminal shell or startup scripts \] + +GISBASE +directory where GRASS lives. This is set automatically by the startup +script. + +GISRC +name of `$HOME/.grass8/rc` file. Defines the system wide value when +starting a GRASS session. Within a GRASS session, a temporary copy of +this file will be used. + +GRASS_ADDON_PATH +\[grass startup script, g.extension\] +specifies additional path(s) containing local and/or custom GRASS +modules extra to the standard distribution. + +GRASS_ADDON_BASE +\[grass startup script\] +allows specifying additional GISBASE for local GRASS modules (normally +installed as GRASS Addons by `g.extension` module) extra to standard +distribution. The default on GNU/Linux is `$HOME/.grass8/addons`, on MS +Windows `%APPDATA%\Roaming\GRASS8\addons`. + +GRASS_ADDON_ETC +\[libgis, g.findetc\] +specify paths where support files (etc/) may be found external to +standard distribution. + +GRASS_COMPATIBILITY_TEST +\[libgis\] +By default it is not possible to run C modules with a libgis that has a +different `GIS_H_VERSION`, the compatibility test will exit with a fatal +error. Setting this variable to 0 (zero) with +`GRASS_COMPATIBILITY_TEST=0` allows the test to be passed with a +warning. + +GRASS_COMPRESSOR +\[libraster\] +the compression method for new raster maps can be set with the +environment variable GRASS_COMPRESSOR. Supported methods are RLE, ZLIB, +LZ4, BZIP2, and ZSTD. The default is ZSTD if available, otherwise ZLIB, +which can be changed with e.g. `GRASS_COMPRESSOR=ZSTD`, granted that +GRASS has been compiled with the requested compressor. Compressors that +are always available are RLE, ZLIB, and LZ4. The compressors BZIP2 and +ZSTD must be enabled when configuring GRASS for compilation. + +GRASS_CONFIG_DIR +\[grass startup script\] +specifies root path for GRASS configuration directory. If not specified, +the default placement of the configuration directory is used: `$HOME` on +GNU/Linux, `$HOME/Library` on Mac OS X, and `%APPDATA%` on MS Windows. + +GRASS_DB_ENCODING +\[various modules, wxGUI\] +encoding for vector attribute data (utf-8, ascii, iso8859-1, koi8-r) + +GIS_ERROR_LOG +If set, GIS_ERROR_LOG should be the absolute path to the log file (a +relative path will be interpreted relative to the process' cwd, not the +cwd at the point the user set the variable). If not set, +`$HOME/GIS_ERROR_LOG` is used instead. The file will only be used if it +already exists. + +GRASS_ERROR_MAIL +set to any value to send user mail on an error or warning that happens +while stderr is being redirected. + +GRASS_FONT +\[display drivers\] +specifies the font as either the name of a font from +`$GISBASE/etc/fontcap` (or alternative fontcap file specified by +GRASS_FONT_CAP), or alternatively the full path to a FreeType font file. + +GRASS_ENCODING +\[display drivers\] +the encoding to be assumed for text which is drawn using a freetype +font; may be any encoding know to *iconv*. + +GRASS_FONT_CAP +\[g.mkfontcap, d.font, display drivers\] +specifies an alternative location (to `$GISBASE/etc/fontcap`) for the +font configuration file. + +GRASS_FULL_OPTION_NAMES +\[parser\] +Generates a warning if GRASS_FULL_OPTION_NAMES is set (to anything) and +a found string is not an exact match for the given string. + +GRASS_GUI +either `text` (text user interface), `gtext` (text user interface with +GUI welcome screen), or `gui` (graphical user interface) to define +non-/graphical startup. Can also specify the name of the GUI to use, +e.g. `wxpython` (*[wxGUI](wxGUI.md)*). Also exists as a GRASS gisenv +variable (see below). If this shell variable exists at GRASS startup, it +will determine the GUI used. If it is not defined startup will default +to the last GUI used. + +GRASS_HTML_BROWSER +\[init.sh, wxgui\] +defines name of HTML browser. For most platforms this should be an +executable in your PATH, or the full path to an executable. +Mac OS X runs applications differently from the CLI. Therefore, +GRASS_HTML_BROWSER should be the application's signature, which is a +domain-like name, just reversed, i.e. com.apple.Safari. To find an +application's signature, type the following in a Terminal (fill in the +path to the application you are interested in, for example: +/Applications/Safari.app): +    `grep -A 1 "CFBundleIdentifier"` +*/path/to/application.app*`/Contents/Info.plist` +  The signature is the \ following the \, without the +bracketing \ tags. + +GRASS_INT_ZLIB +\[libraster\] +if the environment variable GRASS_INT_ZLIB exists and has the value 0, +new compressed *integer* (CELL type) raster maps will be compressed +using RLE compression. + +If the variable doesn't exist, or the value is non-zero, zlib +compression will be used instead. Such rasters will have a `compressed` +value of 2 in the cellhd file. + +Obviously, decompression is controlled by the raster's `compressed` +value, not the environment variable. + +GRASS_ZLIB_LEVEL +\[libgis\] +if the environment variable GRASS_ZLIB_LEVEL exists and its value can be +parsed as an integer, it determines the compression level used when new +compressed raster maps are compressed using zlib compression. This +applies to all raster map types (CELL, FCELL, DCELL). + +Valid zlib compression levels are -1 to 9. The `GRASS_ZLIB_LEVEL=-1` +corresponds to the zlib default value (equivalent to +`GRASS_ZLIB_LEVEL=6`). Often `GRASS_ZLIB_LEVEL=1` gives the best +compromise between speed and compression. + +If the variable doesn't exist, or the value cannot be parsed as an +integer, zlib's default compression level 6 will be used. + +GRASS_MESSAGE_FORMAT +\[various modules, wxGUI\] +it may be set to either + +- `standard` - sets percentage output and message formatting style to + standard formatting, +- `gui` - sets percentage output and message formatting style to GUI + formatting, +- `silent` - disables percentage output and error messages, +- `plain` - sets percentage output and message formatting style to ASCII + output without rewinding control characters. + +GRASS_MOUSE_BUTTON +\[various modules\] +swaps mouse buttons for two-button or left-handed mice. Its value has +three digits 1, 2, and 3, which represent default left, middle, and +right buttons respectively. Setting to `132` will swap middle and right +buttons. Note that this variable should be set before a display driver +is initialized (e.g., `d.mon x0`). + +GRASS_PAGER +\[various modules\] +it may be set to either `less`, `more`, or `cat`. + +GRASS_PERL +\[used during install process for generating man pages\] +set Perl with path. + +GRASS_PROXY +\[used during addon install/reinstall process for generating man pages +(download commit from GitHub API server and remote modules.xml file)\] +set the proxy with: `GRASS_PROXY="http=,ftp="`. + +GRASS_SKIP_MAPSET_OWNER_CHECK +By default it is not possible to work with MAPSETs that are not owned by +current user. Setting this variable to any non-empty value allows the +check to be skipped. + +GRASS_SH +\[shell scripts on Windows\] +path to bourne shell interpreter used to run shell scripts. + +GRASS_SIGSEGV_ON_ERROR +Raise SIGSEGV if an error occurs\] +This variable can be set for debugging purpose. The call of +G_fatal_error() will end in a segmentation violation. GDB can be used to +trace the source of the error. + +GRASS_PYTHON +\[wxGUI, Python Ctypes\] +set to override Python executable. +On Mac OS X this should be the `pythonw` executable for the wxGUI to +work. + +GRASS_VECTOR_LOWMEM +\[vectorlib\] +If the environment variable GRASS_VECTOR_LOWMEM exists, memory +consumption will be reduced when building vector topology support +structures. Recommended for creating large vectors. + +GRASS_VECTOR_OGR +\[vectorlib, v.external.out\] +If the environment variable GRASS_VECTOR_OGR exists and vector output +format defined by *[v.external.out](v.external.out.md)* is PostgreSQL, +vector data is written by OGR data provider even the native PostGIS data +provider is available. + +GRASS_VECTOR_EXTERNAL_IMMEDIATE +\[vectorlib, v.external.out\] +If the environment variable GRASS_VECTOR_EXTERNAL_IMMEDIATE exists and +vector output format defined by *[v.external.out](v.external.out.md)* is +non-native, vector features are written to output external datasource +immediately. By default, the vector library writes output data to a +temporary vector map in native format and when closing the map, the +features are transferred to output external datasource. Note: if output +vector format is topological PostGIS format, then the vector library +writes features immediately to output database (in this case +GRASS_VECTOR_EXTERNAL_IMMEDIATE is ignored). + +GRASS_VECTOR_EXTERNAL_IGNORE +\[vectorlib\] +If the environment variable GRASS_VECTOR_EXTERNAL_IGNORE exists, output +vector format defined by *[v.external.out](v.external.out.md)* is +ignored. The format is always native. + +GRASS_VECTOR_TEMPORARY +\[vectorlib\] +If the environment variable GRASS_VECTOR_TEMPORARY exists, GRASS vector +library will operate on temporary vector maps. New vector maps will be +created in temporary directory (see GRASS_VECTOR_TMPDIR_MAPSET +variable), existing vector maps will be read (if found) also from this +directory. It may be set to either: + +- `keep` - the temporary vector map is not deleted when closing the map. +- `move` - the temporary vector map is moved to the current mapset when + closing the map. +- `delete` - the temporary vector map is deleted when closing the map. + +Default value is `keep`. Note that temporary vector maps are not visible +to the user via *[g.list](g.list.md)* or *[wxGUI](wxGUI.md)*. They are +used internally by the GRASS modules and deleted automatically when +GRASS session is quited. + +GRASS_VECTOR_TMPDIR_MAPSET +\[vectorlib\] +By default GRASS temporary directory is located in +`$LOCATION/$MAPSET/.tmp/$HOSTNAME`. If GRASS_VECTOR_TMPDIR_MAPSET is set +to '0', the temporary directory is located in TMPDIR (environmental +variable defined by the user or GRASS initialization script if not +given). +Important note: This variable is currently used only in vector library. +In other words the variable is ignored by raster or raster3d library. + +GRASS_VECTOR_TOPO_DEBUG +\[vectorlib, v.generalize\] +If the environment variable GRASS_VECTOR_TOPO_DEBUG exists, +*[v.generalize](v.generalize.md)* runs in extremely slow debug mode. + +GRASS_WXBUNDLED +\[wxGUI\] +set to tell wxGUI that a bundled wxPython will be used. +When set, the wxGUI will not check the wxPython version, as this +function is incompatible with a bundled wxPython. It is up to the +packager to make sure that a compatible wxPython version is bundled. + +GRASS_WXVERSION +\[wxGUI\] +set to tell wxGUI which version of wxPython to use. +When set, the wxGUI will select the given wxPython version. It's useful +when multiple versions of wxPython are installed and the user wants to +run wxGUI with non-default wxPython version. + +GRASS_XTERM +\[lib/init/grass-xterm-wrapper, lib/init/grass-xterm-mac\] +set to any value (e.g. rxvt, aterm, gnome-terminal, konsole) to +substitute 'x-terminal-emulator' or 'xterm'. The Mac OS X app startup +defaults to an internal '\$GISBASE/etc/grass-xterm-mac', which emulates +the necessary xterm functionality in Terminal.app. + +GRASS_UI_TERM +set to any value to use the terminal based parser. + +GRASS_VERSION +reports the current version number (used by R-stats interface etc); +should not be changed by user. + +GRASS_NO_GLX_PBUFFERS +\[nviz\] +set to any value to disable the use of GLX Pbuffers. + +GRASS_NO_GLX_PIXMAPS +\[nviz\] +Set to any value to disable the use of GLX Pixmaps. + +OMP_NUM_THREADS +\[OpenMP\] +If OpenMP support is enabled this limits the number of threads. The +default is set to the number of CPUs on the system. Setting to '1' +effectively disables parallel processing. + +TMPDIR, TEMP, TMP +\[Various GRASS GIS commands and wxGUI\] +The default wxGUI temporary directory is chosen from a +platform-dependent list, but the user can control the selection of this +directory by setting one of the TMPDIR, TEMP or TMP environment +variables Hence the wxGUI uses $TMPDIR if it is set, then $TEMP, +otherwise /tmp. + +### List of selected GRASS environment variables for rendering + +> \[ In addition to those which are understood by specific *[GRASS +> display drivers](displaydrivers.md)*, the following variables affect +> rendering. \] + +GRASS_RENDER_IMMEDIATE +tells the display library which driver to use; possible values: +*[cairo](cairodriver.md)*, *[png](pngdriver.md)*, *[ps](psdriver.md)*, +*[html](htmldriver.md)* or *default*. +Default display driver is *[cairo](cairodriver.md)* (if available) +otherwise *[png](pngdriver.md)*. + +GRASS_RENDER_WIDTH +defines the width of output image (default is 640). + +GRASS_RENDER_HEIGHT +defines the height of output image (default is 480). + +GRASS_RENDER_FILE +the name of the resulting image file. + +GRASS_RENDER_FRAME +contains 4 coordinates, *top,bottom,left,right* (pixel values) with +respect to the top left corner of the output image, defining the initial +frame. + +GRASS_RENDER_LINE_WIDTH +defines default line width. + +GRASS_RENDER_TEXT_SIZE +defines default text size. + +GRASS_RENDER_COMMAND +external command called by display library to render data (see example +in *[display drivers](displaydrivers.md)* page for details). +Currently only Python scripts are supported. + +For specific driver-related variables see: + +- *[Cairo display driver](cairodriver.md)* +- *[PNG display driver](pngdriver.md)* +- *[PS (Postscript) display driver](psdriver.md)* +- *[HTML display driver](htmldriver.md)* + +### List of selected internal GRASS environment variables + +> \[ These variables are intended **for internal use only** by the GRASS +> software to facilitate communication between the GIS engine, GRASS +> scripts, and the GUI. The user should not set these in a GRASS +> session. They are meant to be set locally for specific commands. \] + +GRASS_OVERWRITE +\[all modules\] +toggles map overwrite. + +- 0 - maps are protected (default), +- 1 - maps with identical names will be overwritten. + +This variable is automatically created by *[g.parser](g.parser.md)* so +that the `--overwrite` option will be inherited by dependent modules as +the script runs. Setting either the GRASS_OVERWRITE environment variable +or the OVERWRITE gisenv variable detailed below will cause maps with +identical names to be overwritten. + +GRASS_VERBOSE +\[all modules\] +toggles verbosity level + +- -1 - complete silence (also errors and warnings are discarded) +- 0 - only errors and warnings are printed +- 1 - progress and important messages are printed (percent complete) +- 2 - all module messages are printed +- 3 - additional verbose messages are printed + +This variable is automatically created by *[g.parser](g.parser.md)* so +that the `--verbose` or `--quiet` flags will be inherited by dependent +modules as the script runs. + +GRASS_REGION +\[libgis\] +override region settings, separate parameters with a ";". Format is the +same as in the WIND region settings file. Otherwise use is the same as +WIND_OVERRIDE. + +WIND_OVERRIDE +\[libgis\] +it causes programs to use the specified named region (created with e.g. +`g.region save=...`) to be used as the current region, instead of the +region from the WIND file. + +This allows programs such as the GUI to run external commands on an +alternate region without having to modify the WIND file then change it +back afterwards. + +## List of selected GRASS gisenv variables + +> \[ Use *[g.gisenv](g.gisenv.md)* to get/set/unset/change them \] + +DEBUG +\[entire GRASS\] +sets level of debug message output (0: no debug messages) + +```bash +g.gisenv set=DEBUG=0 +``` + +WX_DEBUG +\[wxGUI\] +sets level of debug message output for *[wxGUI](wxGUI.md)* (0: no debug +messages, 1-5 debug levels) + +GISDBASE +initial database + +GIS_LOCK +lock ID to prevent parallel GRASS use, +process id of the start-up shell script + +GUI +See `GRASS_GUI` environmental variable for details. + +LOCATION +full path to project (previously called location) directory + +LOCATION_NAME +initial project name + +MAPSET +initial mapset + +MEMORYMB +\[entire GRASS with focus on raster related data processing\] +sets the maximum memory to be used (in MB), i.e. the cache size for +raster rows + +```bash +# set to 6 GB (default: 300 MB) +g.gisenv set="MEMORYMB=6000" +``` + +NPROCS +sets the number of threads for parallel computing + +```bash +# set to use 12 threads (default: 1) +g.gisenv set="NPROCS=12" +``` + +OVERWRITE +\[all modules\] +toggles map overwrite. + +- 0 - maps are protected (default), +- 1 - maps with identical names will be overwritten. + +This variable is automatically created by *[g.parser](g.parser.md)* so +that the `--overwrite` option will be inherited by dependent modules as +the script runs. Setting either the GRASS_OVERWRITE environment variable +or the OVERWRITE gisenv variable detailed below will cause maps with +identical names to be overwritten. + +## GRASS-related Files + +`$HOME/.grass8/rc` +stores the GRASS gisenv variables (not shell environment variables) + +`$HOME/.grass8/bashrc` +stores the shell environment variables (Bash only) + +`$HOME/.grass8/env.bat` +stores the shell environment variables (MS Windows only) + +`$HOME/.grass8/login` +stores the DBMI passwords in this hidden file. Only the file owner can +access this file. + +`$HOME/GIS_ERROR_LOG` +if this file exists then all GRASS error and warning messages are logged +here. Applies to current user. To generate the file, use: +`touch $HOME/GIS_ERROR_LOG` +See also GIS_ERROR_LOG variable. + +Note: On MS Windows the files are stored in `%APPDATA%`. + +## SEE ALSO + +*[g.gisenv](g.gisenv.md), [g.parser](g.parser.md)* diff --git a/lib/pngdriver/pngdriver.md b/lib/pngdriver/pngdriver.md new file mode 100644 index 00000000000..f6b69343456 --- /dev/null +++ b/lib/pngdriver/pngdriver.md @@ -0,0 +1,93 @@ +*PNG display driver* to create PNG, PPM, or BMP images. + +## DESCRIPTION + +The PNG driver generates PNG, PPM, or BMP images from GRASS display +commands. Per default PNG files are written with this driver. This +driver is used by default if *[Cairo driver](cairodriver.md)* is not +available. + +## USAGE + +### Environment variables + +The PNG driver can be enabled by setting **GRASS_RENDER_IMMEDIATE** +variable, eg. + +```bash +export GRASS_RENDER_IMMEDIATE=png +``` + +Several environment variables affect the operation of the PNG driver: + +- **GRASS_RENDER_WIDTH=xxx** + the width of the image map (default is 640). +- **GRASS_RENDER_HEIGHT=yyy** + the height of the image map (default is 480). +- **GRASS_RENDER_BACKGROUNDCOLOR=RRGGBB** + specifies the background color to use in RGB notation (hex or R:G:B + values). Named colors are also supported. Default is **FFFFFF** + (white). +- **GRASS_RENDER_TRANSPARENT=\[TRUE\|FALSE\]** + sets transparent background on (TRUE) or off (FALSE, default). +- **GRASS_RENDER_TRUECOLOR=\[TRUE\|FALSE\]** + sets true-color support. Default is TRUE. +- **GRASS_RENDER_FILE=filename** + the filename to put the resulting image in, default is `map.png`. If + you set GRASS_RENDER_FILE to a filename which ends in ".ppm", a PPM + file will be created (with alpha channel stored in a PGM image, if + applicable). If you set GRASS_RENDER_FILE to a filename which ends in + ".bmp", a 32-bpp BMP file will be created (these are not readable by + some older viewers). +- **GRASS_RENDER_FILE_COMPRESSION=\[0\|1\|9\]** + compression level of PNG files (0 = none, 1 = fastest, 9 = best, + default is 6) +- **GRASS_RENDER_FILE_READ** + if `TRUE`, the PNG driver will initialize the image from the contents + of GRASS_RENDER_FILE. +- **GRASS_RENDER_FILE_MAPPED** + if `TRUE`, the PNG driver will map GRASS_RENDER_FILE as its + framebuffer, rather than using memory. This only works with BMP files. + +### Example + +```bash +export GRASS_RENDER_IMMEDIATE=png +export GRASS_RENDER_TRUECOLOR=TRUE + +g.region raster=elevation +d.rast elevation +d.vect roadsmajor color=red +``` + +This writes a file named `map.png` in your current directory. + +## NOTES + +The PNG driver uses the libpng (see the +[libpng](http://www.libpng.org/pub/png/) home page) and zlib (see the +[zlib](http://www.zlib.net) home page), all which needs to be installed +for the PNG driver to work (it's worth it). + +The resolution of the output images is defined by current region +extents. Use `g.region -p` to get the number of rows and cols and use +the environment variables to set the image size. If you would like a +larger image, multiply both rows and cols by the same whole number to +preserve the aspect ratio. + +Further PNG file processing (e.g. quantization to 1 bit for monochrome +images) can be done with `pnmquant` of the +[netpbm](https://netpbm.sourceforge.net/) tools. + +## SEE ALSO + +*[Cairo driver](cairodriver.md), [PS driver](psdriver.md), [HTML +driver](htmldriver.md), [variables](variables.md)* + +*[d.rast](d.rast.md), [d.vect](d.vect.md), [d.mon](d.mon.md), +[d.erase](d.erase.md), [d.redraw](d.redraw.md)* + +## AUTHORS + +Original version: Per Henrik Johansen \<*phj (at) norgit.no*\> +Rewritten by: Glynn Clements, 2003 diff --git a/lib/psdriver/psdriver.md b/lib/psdriver/psdriver.md new file mode 100644 index 00000000000..a8de6f33f31 --- /dev/null +++ b/lib/psdriver/psdriver.md @@ -0,0 +1,79 @@ +*PS display driver* to create PostScript files. + +## DESCRIPTION + +The PS driver generates a PostScript file from GRASS display commands. + +## USAGE + +### Environment variables + +The PS driver can be enabled by setting **GRASS_RENDER_IMMEDIATE** +variable, eg. + +```bash +export GRASS_RENDER_IMMEDIATE=ps +``` + +Several environment variables affect the operation of the PS driver: + +- **GRASS_RENDER_WIDTH=xxx** + the width of the image map (default is 640). +- **GRASS_RENDER_HEIGHT=yyy** + the height of the image map (default is 480). +- **GRASS_RENDER_TRUECOLOR=\[TRUE\|FALSE\]** + sets true-color support. Default is FALSE. +- **GRASS_RENDER_FILE** + name of output file. If it ends with ".eps" an EPS file will be + created. +- **GRASS_RENDER_PS_PAPER** + sets the screen dimensions and margins to fit a standard paper size, + see also GRASS_RENDER_WIDTH, GRASS_RENDER_HEIGHT. +- **GRASS_RENDER_PS_LANDSCAPE** + if `TRUE`, the screen is rotated 90 degrees counter-clockwise so that + a "landscape" screen fits better on "portrait" paper. +- **GRASS_RENDER_PS_HEADER** + if `FALSE`, the output is appended to any existing file, and no prolog + or setup sections are generated. +- **GRASS_RENDER_PS_TRAILER** + if `FALSE`, no trailer section is generated. + +### Example + +```bash +export GRASS_RENDER_IMMEDIATE=ps +export GRASS_RENDER_TRUECOLOR=TRUE + +g.region raster=elevation +d.rast elevation +d.vect roadsmajor color=red +``` + +This writes a file named `map.ps` in your current directory. + +## NOTES + +The resolution of the output files is defined by current region extents. +Use `g.region -p` to get the number of rows and cols and use the +environment variables to set the image size. If you would like a larger +image, multiply both rows and cols by the same whole number to preserve +the aspect ratio. + +GRASS_RENDER_TRUECOLOR requires either PostScript level 2 or level 1 +plus the colorimage and setrgbcolor operators (this is the case for +colour printers which pre-date level 2 PostScript). + +Masked images (`d.rast`, `d.rgb`, `d.his -n`) require PostScript level +3. + +## SEE ALSO + +*[Cairo driver](cairodriver.md), [PNG driver](pngdriver.md), [HTML +driver](htmldriver.md), [variables](variables.md)* + +*[d.rast](d.rast.md), [d.vect](d.vect.md), [d.mon](d.mon.md), +[d.erase](d.erase.md), [d.redraw](d.redraw.md)* + +## AUTHOR + +Glynn Clements, 2007 diff --git a/lib/raster3d/test/test.raster3d.lib.md b/lib/raster3d/test/test.raster3d.lib.md new file mode 100644 index 00000000000..dbbd1226712 --- /dev/null +++ b/lib/raster3d/test/test.raster3d.lib.md @@ -0,0 +1,9 @@ +## DESCRIPTION + +*test.raster3d.lib* is a module dedicated for testing the raster 3d +library functionality and to perform benchmark runs. This module is used +by the testing framework to perform library tests. + +## AUTHOR + +Sören Gebbert diff --git a/lib/vector/rtree/test_suite/test.rtree.lib.md b/lib/vector/rtree/test_suite/test.rtree.lib.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/lib/vector/vectorascii.md b/lib/vector/vectorascii.md new file mode 100644 index 00000000000..795fcedee27 --- /dev/null +++ b/lib/vector/vectorascii.md @@ -0,0 +1,131 @@ +A vector map in GRASS native vector format may contain a mix of +*primitives* including points, lines, boundaries, centroids, areas, +faces, and kernels. The GRASS ASCII vector format may contain also a +*header* with various metadata (see example below). + +The header is similar as the head file of vector binary format but +contains bounding box also. Key words are: + +```bash +ORGANIZATION +DIGIT DATE +DIGIT NAME +MAP NAME +MAP DATE +MAP SCALE +OTHER INFO +ZONE +WEST EDGE +EAST EDGE +SOUTH EDGE +NORTH EDGE +MAP THRESH +``` + +The body begins with the row: + +```bash +VERTI: +``` + +followed by records of primitives: + +```bash +TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES] + X Y [Z] +.... + X Y [Z] +[ LAYER CATEGORY] +.... +[ LAYER CATEGORY] +``` + +Everything above in `[ ]` is optional. + +The primitive codes are as follows: + +- 'P': point +- 'L': line +- 'B': boundary +- 'C': centroid +- 'F': face (3D boundary) +- 'K': kernel (3D centroid) +- 'A': area (boundary) - better use 'B'; kept only for backward + compatibility + +The coordinates are listed following the initial line containing the +primitive code, the total number of coordinates in the series, and +(optionally) the number of categories (1 for a single layer, higher for +multiple layers). Below that 1 or several lines follow to indicate the +layer number and the category number (ID). + +The order of coordinates is + +```bash +X Y [Z] +``` + +In pre-GRASS 6 versions of the ASCII format, the order of coordinates +was different: + +```bash +Y X +``` + +Latitude/Longitude data may be given in a number of ways. Decimal +degrees must be positive or negative instead of using a hemisphere +letter. Mixed coordinates must use a hemisphere letter. Whole minutes +and seconds must always contain two digits (example: use +`167:03:04.567`; and not `167:3:4.567`). + +Acceptable formats: +*key: D=Degrees; M=Minutes; S=Seconds; h=Hemisphere (N,S,E,W)* + +- `(+/-)DDD.DDDDD` +- `DDDh` +- `DDD:MMh` +- `DDD:MM.MMMMMh` +- `DDD:MM:SSh` +- `DDD:MM:SS.SSSSSh` + +## EXAMPLES + +```bash +ORGANIZATION: GRASS Development Team +DIGIT DATE: 1/9/2005 +DIGIT NAME: - +MAP NAME: test +MAP DATE: 2005 +MAP SCALE: 10000 +OTHER INFO: Test polygons +ZONE: 0 +MAP THRESH: 0.500000 +VERTI: +B 6 + 5958812.48844435 3400828.84221011 + 5958957.29887089 3400877.11235229 + 5959021.65906046 3400930.7458436 + 5959048.47580612 3400973.65263665 + 5959069.92920264 3401032.64947709 + 5958812.48844435 3400828.84221011 +C 1 1 + 5958952.42189184 3400918.23126419 + 1 20 +B 4 + 5959010.9323622 3401338.36037757 + 5959096.7459483 3401370.54047235 + 5959091.38259917 3401450.99070932 + 5959010.9323622 3401338.36037757 +C 1 1 + 5959063.08352122 3401386.98533277 + 1 21 +``` + +In this case the vector map contains 2 boundaries (first boundary with 6 +vertices, second with 4 vertices) without category and 2 centroids with +category number 20 and 21 (layer 1). + +## SEE ALSO + +*[v.in.ascii](v.in.ascii.md), [v.out.ascii](v.out.ascii.md), +[v.edit](v.edit.md), [v.support](v.support.md)* diff --git a/man/mkdocs/overrides/partials/footer.md b/man/mkdocs/overrides/partials/footer.md new file mode 100644 index 00000000000..d8bfdeb76b2 --- /dev/null +++ b/man/mkdocs/overrides/partials/footer.md @@ -0,0 +1,71 @@ +{% if "navigation.footer" in features %} {% if page.previous_page or +page.next_page %} {% if page.meta and page.meta.hide %} {% set hidden = +"hidden" if "footer" in page.meta.hide %} {% endif %} + +{% if page.previous_page %} {% set direction = lang.t("footer.previous") +%} + +
+ +{% set icon = config.theme.icon.previous or "material/arrow-left" %} {% +include ".icons/" ~ icon ~ ".svg" %} + +
+ +
+ + {{ direction }} + +
+ +{{ page.previous_page.title }} + +
+ +
+ +{% endif %} {% if page.next_page %} {% set direction = +lang.t("footer.next") %} + + +
+ + {{ direction }} + +
+ +{{ page.next_page.title }} + +
+ +
+ +
+ +{% set icon = config.theme.icon.next or "material/arrow-right" %} {% +include ".icons/" ~ icon ~ ".svg" %} + +
+ +{% endif %} + +{% endif %} {% endif %} + +
+ +[Main index](./index.md) \| [Topics index](./topics.md) \| [Keywords +index](./keywords.md) \| [Graphical index](./graphical_index.md) \| +[Full index](./full_index.md) + +
+ +{% include "partials/copyright.html" %} {% if config.extra.social %} {% +include "partials/social.html" %} {% endif %} + +
+ +
diff --git a/misc/m.cogo/m.cogo.md b/misc/m.cogo/m.cogo.md new file mode 100644 index 00000000000..564730b8581 --- /dev/null +++ b/misc/m.cogo/m.cogo.md @@ -0,0 +1,140 @@ +## DESCRIPTION + +*m.cogo* converts data points between bearing and distance and X,Y +coordinates. Only simple bearing/distance or coordinate pairs are +handled. It assumes a cartesian coordinate system. + +Input can be entered via standard input (default) or from the file +**input=***name*. Specifying the input as "-" also specifies standard +input, and is useful for using the program in a pipeline. Output will be +to standard output unless a file name other than "-" is specified. The +input file must closely adhere to the following format, where up to a 10 +character label is allowed but not required (see **-l** flag). + +**Example COGO input:** + +```bash + P23 N 23:14:12 W 340 + P24 S 04:18:56 E 230 + ... +``` + +The first column may contain a label and you must use the **-l** flag so +the program knows. This is followed by a space, and then either the +character 'N' or 'S' to indicate whether the bearing is relative to the +north or south directions. After another space, the angle begins in +degrees, minutes, and seconds in "DDD:MM:SS.SSSS" format. Generally, the +angle can be of the form *digits + separator + digits + separator + +digits \[+ '.' + digits\]*. A space follows the angle, and is then +followed by either the 'E' or 'W' characters. A space separates the +bearing from the distance (which should be in appropriate linear units). + +**Output of the above input:** + +```bash + -134.140211 312.420236 P23 + -116.832837 83.072345 P24 + ... +``` + +Unless specified with the **coord** option, calculations begin from +(0,0). + +## NOTES + +For those unfamiliar with the notation for bearings: Picture yourself in +the center of a circle. The first hemispere notation tell you whether +you should face north or south. Then you read the angle and either turn +that many degrees to the east or west, depending on the second +hemisphere notation. Finally, you move \ units in that +direction to get to the next station. + +*m.cogo* can be run either non-interactively or interactively. The +program will be run non-interactively if the user specifies any +parameter or flag. Use "m.cogo -", to run the program in a pipeline. +Without any flags or parameters, *m.cogo* will prompt for each value +using the familiar GRASS parser interface. + +This program is very simplistic, and will not handle deviations from the +input format explained above. Currently, the program doesn't do anything +particularly useful with the output. However, it is envisioned that this +program will be extended to provide the capability to generate vector +and/or sites layers. + +Lines may be closed by using the **-c** flag or snapped with *v.clean*, +lines may be converted to boundaries with *v.type*, and closed +boundaries may be converted to areas with *v.centroids*. + +## EXAMPLES + +```bash + m.cogo -l in=cogo.dat +``` + +Where the `cogo.dat` input file looks like: + +```bash +# Sample COGO input file -- This defines an area. +#