grass
grass copied to clipboard
OSGeo
wxGUI: Minimal changes to rename location to project
This renames location to project in user messages in wxGUI.
This does not change any documentation or variable names. It does not change names outside of wxGUI.
This changes only location to project. It leaves mapset as is because there seems to be much higher consensus about renaming location to project than about renaming mapset in general.
Are we heading for another field/layer type of confusion?
I guess so. In addition, this PR could potentially lead to misleading names of existing "locations" because not all location names are project names and vice versa. I think this change deserves a "major" version because it's such a big (at least to me) change in semantics.
there seems to be much higher consensus about renaming location to project than about renaming mapset in general.
I think I have missed this discussion. Any link to this consensus would be great!
Notes from GRASS GIS at OSGeo Community Sprint 2022 discussing also other possible renames (not considered now): https://grasswiki.osgeo.org/wiki/GRASS_GIS_at_OSGeo_Community_Sprint_2022#Discuss_naming_and_presentation_of_GRASS_GIS_data_hierarchy
I have long thought that changing the name of locations to something else could make GRASS more approachable, especially for new users. The reason is that locations are how GRASS manages projections (CRS), and do not represent a particular geographic "location". That may have been the original usage, but it is no longer the case.
However, changing the name to "project" does not help and in fact will add more confusion. To most people, a "project" implies a collection of maps, the way they are overlayed, and displayed, and perhaps any ancillary visualizations or analyses to go with them. This is the case for other widely used GIS platforms that users may encounter.
For ArcGIS: " A project is a collection of related items—which may include maps, layouts, item connections, and many other resources—that contribute to a common purpose."
For QGIS: "The state of your QGIS session is called a project." It includes much of the same range of geospatial data as ArcGIS projects.
In GRASS, a "workspace" is most analogous to projects in Arc and Q. But "workspace" is also a widely understood term and seems OK in this context.
Calling a location a project suggests that it is analogous to the way the term is used in other GIS platforms and that is very misleading. A location has a single CRS/projection and all maps stored in a location folder must use that same CRS/projection.
A GRASS location does not represent the state of a GRASS session, the maps displayed, the layouts, the view extent ("region"), styles, colors, etc. Its only purpose is to ensure that all maps (and all mapsets) in a location use the same projection/CRS and will accurately overlay.
Changing the name of locations to "projection" or "CRS" are accurate terms for what locations do.
Calling them "projects" is as misleading (or more so) than calling them locations and will only further confuse future GRASS users.
To be clear, I was not recommending that locations be renamed to workspaces, though that is less confusing than locations or projects. Currently the term "workspace" is used in GRASS in the same way that the term "project" is used in ArcGIS, QGIS, and other programs. If we rename locations to workspaces, we would also need to rename workspaces to something like projects.
Project is a word with a broad meaning. For software, it often refers to whatever is the main native thing the software deals with unless there is another more common name (document, image, database). However, it is a common word outside of GIS and software and people are used to the word coming with different definitions in different contexts.
Reading little further in that ArcGIS Pro documentation page:
A project contains two types of items. One type includes maps, scenes, layouts, and other views of your data. The other type is connections that provide access to the contents of folders, databases, and other resources. ... A project is stored on your computer as a file with the extension .aprx. By default, it is stored in a system folder created with the project. The project file is associated with a geodatabase and a toolbox. Other folders and files, such as the project index and the backup project file, are created with the project or during your ArcGIS Pro session.
The ArcGIS Pro project files are grouped together with actual data storage, not just views or links to data.
While QGIS project does not store data, it stores auxiliary data and it can be stored inside a GeoPackage with the data (so go as far as saying [QGIS] GeoPackage Project.
In cases of ArcGIS and QGIS, actual data storage can be part of the project, so it is not just purely state of the GUI. For wxGUI, the workspace file referred originally to state of the GUI (some windows, added layers, d-command styling, 3D) and now it includes also path to mapset.
The word workspace is used in ArcGIS:
Tools that honor the Current Workspace environment use the workspace specified as the default location for geoprocessing tool inputs and outputs. ... In ArcGIS Pro, the default value for the Scratch Workspace and Current Workspace environments is the project default geodatabase.
So the two closet things we have are what is currently called mapset (not location!) and current working directly (pwd, os.getcwd(), getwd()).
And QGIS documentation uses that to refer to whatever sort of the state of the GUI thing:
QGIS can save the state of your workspace into a QGIS project file using the menu options Project ► Save or Project ► Save As….
That would be the GUI workspace file, except that QGIS project can have associated external data like Shapefile on the disk and the workspace file cannot. However, GRASS GIS can do it in a location, or more precisely in a mapset (v.external, r.external).
A GRASS location (or mapset) does represent the state of what the user was doing in a sense that it has all the data you were working with, history of what you were doing, current computation extent and resolution, default extent, bookmarked extents (spatial bookmarks aka saved regions), associated styles when stored as color tables, labels for cartography (v.label, d.label), links to external data, even your selected CRS.
One may argue that the state of the GUI is missing. I would agree. I think what is now a workspace file would make most sense as part of a mapset (I'm thinking that since I saw the low uptake of workspace file with stored mapset path and the much more successful data management panel).
While projection or CRS is an import part of what location is in GRASS GIS, both projection and CRS refer to something completely different than data storage and what locations do is storing data. They store them in a particular way which involves data format and CRS, but they are more than just data storage, they also store much of the information users generates when working with the software.
From time to time I'm using ArcGIS Pro, here some experiences and thoughts.
- Starting ArcGIS Pro for a new work, for saving a "project" (.aprx), you have to choose a ArcGIS project folder in your file system where .aprx will be saved
- this ArcGIS project folder can be anywhere on your file system; ideally on a dedicated drive or as a subfolder in a dedicated GIS work folder. GRASS GIS is here more structured in a clean way with its GRASS data base, here simplified known as 'GRASSDATA' in the many tutorials (in GRASS > 8 with the nice addition to add more GRASS data bases into the tree).
- data linked in a ArcGIS Pro "project" (.aprx) can be (copied) in the ArcGIS project folder or can be anywhere in the file system. GRASS eqivalent here is r.external/v.external. with the main and important difference that ArcGIS Pro re-projects on the fly while in GRASS GIS all data has to be in the same SRS (side note here: I like the GRASS GIS approach here as some kind of a data integrity check while bringing your data into the same SRS before analysis is done)
- data produced in an ArcGIS work is stored by default into the ArcGIS project folder, e.g. vector data into a file geodatabase and raster data as a raster data file itself or also into a file geodatabase; though a user can define also another place outside of the ArcGIS project folder. again, in GRASS GIS it is a bit more strictly structured as resulting products are stored into the active mapset; additionally, AFAIK GRASS module output can't be saved directly outside a mapset. an extra step is here needed with r.out.gdal/v.out.ogr.
- ArcGIS Pro "project" (.aprx) is partly equivalent to a GRASS GIS workspace file
- ArcGIS PRO is a bit more flexible in saving resulting data comparing to the strict GRASS GIS approach
- with ArcGIS Pro switching to the ArcGIS project folder concept, IMHO GRASS GIS and ArcGIS Pro are not really far away in structuring GIS data, with the main difference of on-the-fly-re-projection ability.
- IMHO, QGIS follows the approach of the now 'old' ArcGIS Map concept; it is not a bad concept, it is one of many concept ideas how GIS data can be structured within your workflows.
- with increasing GIS data amount and GIS data file size nowadays, IMHO a structured data management is the way to go; and GRASS GIS is here with its well founded data concept on a good way.
- to sum it up, it seems to be here more some kind of naming question, and not a concept question.
- here and there there are complaints (thus this PR) that users are not used to GRASS GIS data concepts and naming (location/mapset, etc), on the other hand no one of these people have contributed some input to the discussion
- while re-reading the PR title "Rename location to project", from my own user point of view ;-) : a GIS project is where I store all of my client's data and do my GIS analysis :-)
...I think what is now a workspace file would make most sense as part of a mapset...
A proof of concept available in PR #3113.
@hellik Thank you for these notes. Generally, although partially relevant to this discussion, would you mind reviewing and extending the wiki page called Terminology comparison between ArcGIS and GRASS GIS.
Let me know what you think about these:
- data produced in an ArcGIS work is stored by default into the ArcGIS project folder, e.g. vector data into a file geodatabase and raster data as a raster data file itself or also into a file geodatabase; though a user can define also another place outside of the ArcGIS project folder. again, in GRASS GIS it is a bit more strictly structured as resulting products are stored into the active mapset...
Storing in folder and a file geodatabase sounds very similar to a mapset. Is that your understanding?
...additionally, AFAIK GRASS module output can't be saved directly outside a mapset. an extra step is here needed with r.out.gdal/v.out.ogr.
Outputs can go directly to files outside of a mapset, with r.external.out and v.external.out. They become linked as with v.external and r.external, or in other words, they are automatically added to the project.
- ArcGIS Pro "project" (.aprx) is partly equivalent to a GRASS GIS workspace file
...while the whole ArcGIS Pro project (not just .aprx) is partially equivalent to location and partially to mapset, or not?
- with ArcGIS Pro switching to the ArcGIS project folder concept, IMHO GRASS GIS and ArcGIS Pro are not really far away in structuring GIS data...
I agree. It was a funny moment when I first saw the new ArcGIS Pro approach while in the middle of rethinking all these pieces in GRASS GIS.
...with the main difference of on-the-fly-re-projection ability.
You can actually do it manually and we could implement that programmatically (both) using GDAL VRT (virtual format for both vectors and raster). I'm not saying I have a good experience with that, just that it would be possible to implement that.
- with increasing GIS data amount and GIS data file size nowadays, IMHO a structured data management is the way to go; and GRASS GIS is here with its well founded data concept on a good way.
I think we have already established that in the past. Things like GeoPackage or ArcGIS Pro projects also worked as sort of confirmations of advantages of these concepts.
- to sum it up, it seems to be here more some kind of naming question, and not a concept question.
Yes, it is indeed a naming question. I think we are coming back to the concepts in order to avoid creating more confusion. See rename of vector fields to layers, category versus id, or map versus layer.
- here and there there are complaints (thus this PR) that users are not used to GRASS GIS data concepts and naming (location/mapset, etc), on the other hand no one of these people have contributed some input to the discussion
I'm explaining the database, location, and mapset periodically, so I'm one of them.
If you are after some prior written notes, notes from many of the previous discussions are available here:
- OSGeo Community Sprint 2022 Florence
- Track wiki: New Startup (that has some real gems like: "Workspace is your project and mapset is your workspace...and location is your database, database directory is your grassdata, and current working directory is your user folder")
@hellik Thank you for these notes. Generally, although partially relevant to this discussion, would you mind reviewing and extending the wiki page called Terminology comparison between ArcGIS and GRASS GIS.
will do later, travelling these days.
Let me know what you think about these:
- data produced in an ArcGIS work is stored by default into the ArcGIS project folder, e.g. vector data into a file geodatabase and raster data as a raster data file itself or also into a file geodatabase; though a user can define also another place outside of the ArcGIS project folder. again, in GRASS GIS it is a bit more strictly structured as resulting products are stored into the active mapset...
Storing in folder and a file geodatabase sounds very similar to a mapset. Is that your understanding?
in a broader sense, yes. on the other hand, (GIS) data structure may be given by your organisation, and some flexibility is needed here; but that's another point for discussion.
...additionally, AFAIK GRASS module output can't be saved directly outside a mapset. an extra step is here needed with r.out.gdal/v.out.ogr.
Outputs can go directly to files outside of a mapset, with r.external.out and v.external.out. They become linked as with v.external and r.external, or in other words, they are automatically added to the project.
I've never tried r.external.out and v.external.out for myself. are these tools often used? any figures for that? I use quite often r.external and most raster tools are working nicely with linked raster data (except r. null). with v.external-linked data, there are limitations when topology comes into play.
- ArcGIS Pro "project" (.aprx) is partly equivalent to a GRASS GIS workspace file
...while the whole ArcGIS Pro project (not just .aprx) is partially equivalent to location and partially to mapset, or not?
location yes, a (partial) mapset equivalent I can't see for the moment; more testing is needed. though, one may see here a lack in ArcGIS Pro project structure concept .... ;-)
- with ArcGIS Pro switching to the ArcGIS project folder concept, IMHO GRASS GIS and ArcGIS Pro are not really far away in structuring GIS data...
I agree. It was a funny moment when I first saw the new ArcGIS Pro approach while in the middle of rethinking all these pieces in GRASS GIS.
:-)
...with the main difference of on-the-fly-re-projection ability.
You can actually do it manually and we could implement that programmatically (both) using GDAL VRT (virtual format for both vectors and raster). I'm not saying I have a good experience with that, just that it would be possible to implement that.
not sure on-the-fly-re-projection is always the best choice. for a visual context probably yes, but not for analysis tasks all the time; just think of raster resolution issues or large vector polygons, refering here e.g. to v.proj-option:
smax=float
Maximum segment length in meters in output vector map
Increases accuracy of reprojected shapes, disable with smax=0
while working with large European vector and raster data here in my agency, all these things have to be considered before analysis is started. sometimes in ArcGIS Pro analysis, there are fuzzy analysis error messages; they disappear when data re-projection is done in a well considered way beforehand.
- with increasing GIS data amount and GIS data file size nowadays, IMHO a structured data management is the way to go; and GRASS GIS is here with its well founded data concept on a good way.
I think we have already established that in the past. Things like GeoPackage or ArcGIS Pro projects also worked as sort of confirmations of advantages of these concepts.
yep
- to sum it up, it seems to be here more some kind of naming question, and not a concept question.
Yes, it is indeed a naming question. I think we are coming back to the concepts in order to avoid creating more confusion. See rename of vector fields to layers, category versus id, or map versus layer.
yes. are there e.g. OGC guidelines available for naming streamlining?
- here and there there are complaints (thus this PR) that users are not used to GRASS GIS data concepts and naming (location/mapset, etc), on the other hand no one of these people have contributed some input to the discussion
I'm explaining the database, location, and mapset periodically, so I'm one of them.
If you are after some prior written notes, notes from many of the previous discussions are available here:
Track wiki: New Startup (that has some real gems like: "Workspace is your project and mapset is your workspace...and location is your database, database directory is your grassdata, and current working directory is your user folder")
IMHO it's time for the next step to decide .... ;-D @veroandreo
I've been tied up in a workshop until now. A couple more points.
First, I understand the rationale for this proposal. The term "project" is very generic and could mean many things. The file structure of GRASS could indeed be referred to as projects. This file structure also functions kind of like a "working directory" in Bash, Python, R, etc. My point, however, is about how the user experiences what is called a project rather than the underlying structure of file(s) used to define a project.
For better or worse, a number of GIS platforms (Arc, Q, and even TerrSet) have used the term to refer to the state of the GIS and its environment for display and analysis. The preceding discussion above by others is a thorough and useful one. A GRASS mapset plus a GRASS workspace encompasses most of the ways in which projects are used in other platforms. For example, if we were starting afresh, a case could be made for changing the term "mapset" to "project", and "location" to "mapset". But of course, that would be a mess for GRASS history and current users--and mapset is a perfectly good term for a set of maps that are often used together.
A location, however, is simply a way to ensure that a group of maps and the mapsets in which they are stored all share the same CRS/projection. The term location is indeed a confusing one for what is going on. Changing the name of this feature from location to project can be justified of course, but IMHO, it does not make it any less confusing for people learning to use GRASS. I will have to do the same amount of explanation about what a project is in GRASS as I do now for the term location. In addition, I will need to answer questions as to why it is not the same as the projects they have encountered in other GIS programs.
Finally, if we do go through with this change, we will need to do this throughout GRASS, not just in the GUI. In any module that calls a location currently, it should accept the word project as an alternative. This could be done in the GUI parser I think, but it will also need to be implemented in C-code modules in some way because people will also be wanting to copy commands from the GUIs for each module and paste them into the console or terminal. Perhaps this is in one of the PR's, but I could not tell from the titles.
The idea for this PR is to see how the change will look like in GUI. Changing it elsewhere is a separate issue, possibly more straightforward. We also just released 8.3, so there is some time before 8.4. However, just for more context, here is an adhoc analysis of the APIs:
CLI API
I think the change be fairly smooth. We have a system in place for renames in parser (introduced with renames for 7.0) and we can introduce an additional option in case the automated system is not enough. Here are the tools which are affected:
$ grep -IrnE 'key[^w].*location|G_OPT_M_LOCATION' | grep -vE "current location|key-?frame locations|target location|grass/gis.h|standard_options?.c" | grep -i location
temporal/t.vect.import/t.vect.import.py:69:# % key: location
temporal/t.rast.import/t.rast.import.py:71:# % key: location
general/g.proj/main.c:218: location->key = "location";
general/g.mapset/main.c:61: opt.location = G_define_standard_option(G_OPT_M_LOCATION);
gui/wxpython/image2target/g.gui.image2target.py:33:##%option G_OPT_M_LOCATION
gui/wxpython/image2target/g.gui.image2target.py:34:##% key: source_location
raster/r.in.gdal/main.c:192: parm.outloc->key = "location";
raster/r.proj/main.c:153: inlocation = G_define_standard_option(G_OPT_M_LOCATION);
imagery/i.target/main.c:53: loc->key = "location";
imagery/i.ortho.photo/i.ortho.elev/main.c:69: loc_opt = G_define_standard_option(G_OPT_M_LOCATION);
imagery/i.ortho.photo/i.ortho.target/main.c:56: location_opt = G_define_standard_option(G_OPT_M_LOCATION);
imagery/i.ortho.photo/i.ortho.target/main.c:57: location_opt->key = "target_location";
imagery/i.ortho.photo/i.ortho.target/main.c:63: mapset_opt->key = "mapset_location";
scripts/g.download.location/g.download.location.py:33:# %option G_OPT_M_LOCATION
db/db.databases/main.c:82: location->key = "location";
vector/v.in.lidar/main.c:273: outloc_opt->key = "location";
vector/v.proj/main.c:82: ilocopt = G_define_standard_option(G_OPT_M_LOCATION);
vector/v.in.ogr/main.c:310: param.outloc->key = "location";
$ grep -IrnE 'key[^w].*location|G_OPT_M_LOCATION' | grep -vE "current location|key-?frame locations|target location|grass/gis.h|standard_options?.c" | sed -e s+:.*++g | uniq | wc -l
15
$ ggrep -IrnE 'key[^w].*location' | grep -vE "current location|key-?frame locations|target location|grass/gis.h|standard_options?.c" | sed -e s+:.*++g | uniq | wc -l
10
$ grep -IrnE 'G_OPT_M_LOCATION' | grep -vE "current location|key-?frame locations|target location|grass/gis.h|standard_options?.c" | sed -e s+:.*++g | uniq | wc -l
7
Python API
It is little hard to tell what is the extent of changes needed. grep -IrnE location jupyter/ pygrass/ script/ temporal/ gives a lot of results, but places where it actually matters are much more scarce. I can think of grass.script.setup.init, create_location, create_environment, but in all three cases, the location is mostly used as a (nameless) positional argument, not a keyword argument in user code. Anyway, in many places, a new parameter can be safely introduced without breaking the API. Actually, the current grass.script.setup.init has only one mandatory parameter call path. When only that is provided, it is used as path to mapset, but you can also provide database, location, mapset, i.e., the path then becomes the database directory. User code would not change in either case even if we introduce it as a breaking change (but we will not).
C API
Again, new names can be added in a backwards compatible way. This has the lowest priority, but perhaps it is easy if we are talking just about the API which is all I'm aiming for now. grep -IrnE _location include/grass/ does not give much. You actually get more results with G_database:
grep -IrnE G_database include/grass/
include/grass/defs/gis.h:672:const char *G_database_unit_name(int);
include/grass/defs/gis.h:673:int G_database_unit(void);
include/grass/defs/gis.h:674:const char *G_database_projection_name(void);
include/grass/defs/gis.h:675:const char *G_database_datum_name(void);
include/grass/defs/gis.h:676:const char *G_database_ellipse_name(void);
include/grass/defs/gis.h:677:double G_database_units_to_meters_factor(void);
include/grass/defs/gis.h:678:const char *G_database_epsg_code(void)
...which somewhat suggests that renaming in C API can wait a bit. BTW, if anyone knows why these are called database and not location, please let me know.
@cmbarton If I understand you correctly, your view of location is that it is what tells you (or GRASS GIS) what CRS the data is in. Correct me if I'm wrong, but I think that's also what you expressed in the 2018 discussion: "Use of the anachronistic term “location” to refer to a CRS is a quirk that makes GRASS more confusing to initial users." In this view, renaming location to CRS makes sense. However, while this is a workable understanding of location, I don't think correctly or fully captures what location is. If CRS would be all that location is, deleting location would create data without a CRS, but deleting location, deletes the data, so location is more than just CRS.
A location, however, is simply a way to ensure that a group of maps and the mapsets in which they are stored all share the same CRS/projection.
Location does even more than that. The grouping of mapsts is itself a feature. It organizes your data into mapsets, so you can have related data together, but divided into groups. It allows you to access data in other mapsets in the same location, either through @mapset_name syntax or using search path, but just for reading for data protection reasons. Each location has at least one mapset. This mapset is accessible for reading from the other mapsets even without @mapset_name syntax or using search path so that it can be used for storing the most common data.
You have freedom in how or how much of this you use. You can have one location for each CRS you need to deal with and organize everything else into mapsets. I have now 22 locations not counting those named tests and different versions of NC SPM. Some are named by their CRS, some are not, some have unique CRS, some have the same CRS as the others. Often, one, two or three together are often related to a specific project I'm working on. I have another database directory added in GUI where I have over 5 locations all related to a single project I'm working on.
I will have to do the same amount of explanation about what a project is in GRASS as I do now for the term location.
Importantly, the goal is not to avoid explaining it, the goal is to make the explanations more efficient. Explaining location and especially the database-location-mapset trio often leaves people wondering why they need all these things they have never heard of before. On the other hand, any existing ideas about what project is won't be harmful and will likely be helpful if we go with the idea of project as "stuff you need to achieve something." The same cannot be set about location or CRS.
- "Locations helps you organize your data. All data you work with are in a location. All data in one location have the same CRS. Data in a location is further organized into mapsets."
- "Projects helps you organize your data. All data you work with are in a project. All data in one project have the same CRS. Data in a project is further organized into mapsets."
- "Projects helps you organize your data. All data you work with are in a project. All data in one project have the same CRS. Data in a project is further organized into subprojects."
- "Tuft helps you organize your data. All data you work with are in a tuft. All data in one tuft have the same CRS. Data in a tuft is further organized into culms."
- "Rumen helps you organize your data. All data you work with are in a rumen. All data in one rumen have the same CRS. Data in a rumen is further organized into omasums."
(Number 4 and 5 were contributed by Grassy the Hungry Cow :cow:)
From location, project, tuft, and rumen, project just leads you right to the right ideas here. CRS or projection would require completely different description here because they would need to start from mapset and build up to a CRS or something like that.
In addition, I will need to answer questions as to why it is not the same as the projects they have encountered in other GIS programs.
I don't see how you can avoid this discussion now with location. However, my question is, in what ways is it different? Based on the discussion above, I would say, not that different. Is it different from how people perceive what a project is elsewhere? Maybe. The GRASS project is focused on data rather than visuals. GRASS project enforces data consistency by requiring only one CRS for a project and by using in-project data storage native format by default. It encourages further organization of the data using mapsets (subprojects). At this point, the map compositions you create are saved in a separate file, but the data always stays in the project.
Hi @wenzeslaus. It is clear that project is the way this is going to go. I can deal with it of course. I want to clarify a couple points I made, though not in anticipation of changing anyone's mind on the plan.
@cmbarton If I understand you correctly, your view of location is that it is what tells you (or GRASS GIS) what CRS the data is in. Correct me if I'm wrong, but I think that's also what you expressed in the 2018 discussion: "Use of the anachronistic term “location” to refer to a CRS is a quirk that makes GRASS more confusing to initial users." In this view, renaming location to CRS makes sense. However, while this is a workable understanding of location, I don't think correctly or fully captures what location is. If CRS would be all that location is, deleting location would create data without a CRS, but deleting location, deletes the data, so location is more than just CRS.
A location, however, is simply a way to ensure that a group of maps and the mapsets in which they are stored all share the same CRS/projection.
Location does even more than that. The grouping of mapsts is itself a feature. It organizes your data into mapsets, so you can have related data together, but divided into groups. It allows you to access data in other mapsets in the same location, either through
@mapset_namesyntax or using search path, but just for reading for data protection reasons. Each location has at least one mapset. This mapset is accessible for reading from the other mapsets even without@mapset_namesyntax or using search path so that it can be used for storing the most common data.
No maps are stored directly in a location, only folders. You can make a location with no data at all. The only thing it contains is a PERMANENT folder (initially a mapset without maps) with DEFAULT_WIND, PROJ_INFO, and PROJ_UNITS files. I think that DEFAULT_WIND, defining a geographic extent, is probably the reason that this was originally called a "location".
If you then import or make some maps in folders (mapsets) within a location, and subsequently delete or change PROJ_INFO and PROJ_UNITS, or if you move a mapset folder out of a location, the maps are no longer georegistered correctly. You have the data but it is useless. Other platforms define a map's CRS in other ways. In GRASS it is done with a couple files stored in [location]/PERMANENT. Using external maps in GRASS involves invoking CRS information that is stored somewhere else than [location]/PERMANENT, and these maps not need to be stored in a mapset folder inside a location folder.
This is what I meant by saying that the only GIS function that locations have is assigning a CRS to maps.
You have freedom in how or how much of this you use. You can have one location for each CRS you need to deal with and organize everything else into mapsets. I have now 22 locations not counting those named tests and different versions of NC SPM. Some are named by their CRS, some are not, some have unique CRS, some have the same CRS as the others. Often, one, two or three together are often related to a specific project I'm working on. I have another database directory added in GUI where I have over 5 locations all related to a single project I'm working on.
I have an embarrassing 92 after some recent gleaning
- "Locations helps you organize your data. All data you work with are in a location. All data in one location have the same CRS. Data in a location is further organized into mapsets."
- "Projects helps you organize your data. All data you work with are in a project. All data in one project have the same CRS. Data in a project is further organized into mapsets."
- "Projects helps you organize your data. All data you work with are in a project. All data in one project have the same CRS. Data in a project is further organized into subprojects."
- "Tuft helps you organize your data. All data you work with are in a tuft. All data in one tuft have the same CRS. Data in a tuft is further organized into culms."
- "Rumen helps you organize your data. All data you work with are in a rumen. All data in one rumen have the same CRS. Data in a rumen is further organized into omasums."
(Number 4 and 5 were contributed by Grassy the Hungry Cow 🐮)
Agreed. Changing the name from location to project makes no difference at this stage. Maybe "rumen" is also worth considering ;-)
In addition, I will need to answer questions as to why it is not the same as the projects they have encountered in other GIS programs.
This does not apply for first time GIS students who have never used any other GIS. But increasingly I have students who have used other GIS programs a little and are somewhat familiar with how they organize things. Not a big deal of course, but my long term goal has been to make GRASS easier to use.
So let's go ahead with this experiment. While I don't think it will make GRASS easier to use or learn, I don't believe it will make it any more difficult either.
FWIW: this is the oldest (to my knowledge) reference available online - see Historic citations in the Wiki:
- Shapiro, M., Westervelt, J., Gerdes, D., Higgins, M., & Larson, M. (1989). GRASS 3.0 programmer's manual (No. CERL-ADP-N-89/14). CONSTRUCTION ENGINEERING RESEARCH LAB (ARMY) CHAMPAIGN IL. (PDF: https://apps.dtic.mil/sti/pdfs/ADA252461.pdf)
- --> "Chapter 4. Database Structure", pages 15-17: Location, Mapset, ...
Just to be clear about the scope of this PR. There is 251 places in the GUI code which need further revision, but this PR tries to hit the most important ones to test things out.
$ grep -IrnEi "[^a-z_]locations?[^a-z_]" gui/wxpython | grep -vE 'LOCATION_NAME|pLocation|"location"|self.location|location ?= ?|if .*location.*:|# .*location|""".*location|:param.*location:|:return .*location|{location}|xml/module_tree_menudata.xml|xml/menudata.xml|.pylintrc|menustrings.py| project|project,location' | grep location | wc -l
251
For the GRASS history junkies:
The GRASS 3.0 Programmer's Manual says:
Chapter 4, Database Structure ... The database for GRASS makes use of the UNIX hierarchical directory structure. The top level directory is known as GISDBASE. Users specify this directory when entering GRASS.
Subdirectories under the GISDBASE are known as locations. Locations are independent databases. Users select a location when entering GRASS. All database queries and modifications are made to this location only. ... The full UNIX directory name for the current mapset is $GISDBASE/$LOCATION_NAME/$MAPSET and is returned by the library routine G_location_path. [emphasis mine]
The manual for 4.0 says exactly the same. Today, G_location_path returns path to mapset while the above is returned by G_mapset_path. $LOCATION variable which was path to mapset used to be defined in the interactive shell session and was removed only in v7 (Track Ticket #2681). I did not find an explicit explanation for why the G_database group of functions refers to location, but the description of location in manual more or less provides it: locations are [...] databases in version 3 view except that all of them together are also called a database ("The database for GRASS makes use of...", GISDBASE).
...the word "Location" is capitalized...I suggest that we do the same with the term "Project"...
I think I did most of the capitalization for Location (it kind of went from LOCATION to location and then to Location). Here we are couple years later changing the term completely, so it didn't help much. Can it help a little bit? Maybe.
I'm concerned with whether we will be able to apply this consistently. Will creators of tutorials follow that practice? I did see some people using Location. Are we using this elsewhere? Raster? Vector? Layer? Are there examples outside of GRASS GIS? QGIS is not capitalizing project.
...the word "Location" is capitalized...I suggest that we do the same with the term "Project"...
I think I did most of the capitalization for Location (it kind of went from LOCATION to location and then to Location). Here we are couple years later changing the term completely, so it didn't help much. Can it help a little bit? Maybe.
I'm concerned with whether we will be able to apply this consistently. Will creators of tutorials follow that practice? I did see some people using Location. Are we using this elsewhere? Raster? Vector? Layer? Are there examples outside of GRASS GIS? QGIS is not capitalizing project.
The best we can do is set a good example. And the POSE project will be creating some tutorials and so can set a standard there too. Because of its long legacy, GRASS code and documentation has not been consistent. But this is a good opportunity to be more so at least in regard to these terms.
"Project" capitalized or not:
I think for distinguishing between GRASS project and a general project or any other project, we will need to anyway say "GRASS project". For that, project or Project does not make much difference. The capitalized project also does not really come through when speaking, so lectures, workshops, videos anyway need to use context and GRASS as adjective to make the distinction.
Seeing how things work in the code, when the standard is not automatically enforced by CI, there is little hope that it will be applied by everyone. Given that, I don't have much hope that getting it right in a tutorial in 2024 will particularly help to promote the practice beyond the most active contributors.
With that said, I'm waiting with the merge until this is resolved. While I won't be chasing every mention on mapset to capitalize it, I'm willing to modify the PRs to capitalize project (and mapset) when applicable.
Are there any other opinions on this?
"Project" capitalized or not:
I think for distinguishing between GRASS project and a general project or any other project, we will need to anyway say "GRASS project". For that, project or Project does not make much difference. The capitalized project also does not really come through when speaking, so lectures, workshops, videos anyway need to use context and GRASS as adjective to make the distinction.
Seeing how things work in the code, when the standard is not automatically enforced by CI, there is little hope that it will be applied by everyone. Given that, I don't have much hope that getting it right in a tutorial in 2024 will particularly help to promote the practice beyond the most active contributors.
With that said, I'm waiting with the merge until this is resolved. While I won't be chasing every mention on mapset to capitalize it, I'm willing to modify the PRs to capitalize project (and mapset) when applicable.
Are there any other opinions on this?
When I read @cmbarton explanation I went like: oh, yes, capitalized Project, that sounds good. Now, after reading @wenzeslaus explanation, I'm trying to think on the usage of these concepts once this is merged, and I wonder why capitalizing? Why putting an extra layer of complexity and maintenance burden on ourselves? We sometimes complain or more often hear complaints like this is too complex to explain, people get confused, why all this and such... Capitalizing does not seem to go in the direction of trying to simplify explanations or making the concepts and GRASS database structure sound more natural, i.e., look GRASS has a native format and so you need to convert your data to it, luckily GRASS offers a nice system to store your data in a database organized in projects, these have folders inside or mapsets that help you organize your maps in topics, areas, whatever. The important thing of projects is that they are defined by a CRS, so all maps inside a project will share the same CRS. Do we need to use GRASS database and GRASS projects or GRASS mapsets? We can, but maybe we do not need to... On these lines, I'm more inclined to keep it as simple as possible, so, just project and mapset...
"Project" capitalized or not: I think for distinguishing between GRASS project and a general project or any other project, we will need to anyway say "GRASS project". For that, project or Project does not make much difference. The capitalized project also does not really come through when speaking, so lectures, workshops, videos anyway need to use context and GRASS as adjective to make the distinction. Seeing how things work in the code, when the standard is not automatically enforced by CI, there is little hope that it will be applied by everyone. Given that, I don't have much hope that getting it right in a tutorial in 2024 will particularly help to promote the practice beyond the most active contributors. With that said, I'm waiting with the merge until this is resolved. While I won't be chasing every mention on mapset to capitalize it, I'm willing to modify the PRs to capitalize project (and mapset) when applicable. Are there any other opinions on this?
When I read @cmbarton explanation I went like: oh, yes, capitalized Project, that sounds good. Now, after reading @wenzeslaus explanation, I'm trying to think on the usage of these concepts once this is merged, and I wonder why capitalizing? Why putting an extra layer of complexity and maintenance burden on ourselves? We sometimes complain or more often hear complaints like this is too complex to explain, people get confused, why all this and such... Capitalizing does not seem to go in the direction of trying to simplify explanations or making the concepts and GRASS database structure sound more natural, i.e., look GRASS has a native format and so you need to convert your data to it, luckily GRASS offers a nice system to store your data in a database organized in projects, these have folders inside or mapsets that help you organize your maps in topics, areas, whatever. The important thing of projects is that they are defined by a CRS, so all maps inside a project will share the same CRS. Do we need to use GRASS database and GRASS projects or GRASS mapsets? We can, but maybe we do not need to... On these lines, I'm more inclined to keep it as simple as possible, so, just project and mapset...
The reason is similar to why we spell it GRASS instead of grass. I realize that GRASS is also an acronym but it distinguishes the special usage of it in GRASS from the common usage of a word. Project is a very common word and as proposed, a Project has a specific meaning in GRASS (like Location vs. location).
It's not a huge issue, but it would nice to 1) be consistent, which it is not currently, and 2) clearly signal to users what a GRASS Project is. It is not a matter of trying to force others to use it this way, but my suggestion is that in our docs to be consistent and use capitalization to make usage more clear. For example, "You will need to project all the maps that you use in a project to the same CRS. A GRASS Project is a place to store all the maps from your project that have the same projection." Capitalizing GRASS Project (or even all caps PROJECT) makes these sentences more understandable than they would be otherwise.
It's not a huge issue, but it would nice to 1) be consistent, which it is not currently, and 2) clearly signal to users what a GRASS Project is. It is not a matter of trying to force others to use it this way, but my suggestion is that in our docs to be consistent and use capitalization to make usage more clear. For example, "You will need to project all the maps that you use in a project to the same CRS. A GRASS Project is a place to store all the maps from your project that have the same projection." Capitalizing GRASS Project (or even all caps PROJECT) makes these sentences more understandable than they would be otherwise.
Consistency would be easier to achieve with lower case in my opinion. I think it's common to use lower case, e.g. QGIS project. Clarity can be achieved by other means, e.g. in your sentence you can simply drop the lower case project word and it will work just as well. So I would vote for lower case.
@cmbarton is for Project with capital P or possibly for all caps PROJECT. @veroandreo and @petrasovaa are for all lowercase project.
While I'm author of most of the occurrences of Location with capital L, I must say I did not see much buy-in (no one came up and said, "hey, let's change it everywhere") and I definitively did not see any significant improvement in understanding of Location as a result of that (if there would be any, we would not be here renaming location to project).
Given the difficulties with enforcement of this, lack of application of the same uppercase logic to other concepts (mapset, vector, raster, ...), and the experience with Location with upper case L, I'm for an all lowercase project.
I'm going with project.
Approving reviews would help merging this.
I'm certainly not going to block this. I do want to clarify a couple things. When I recommend using Project instead of project, I'm only referring to places where users will see the word: in official GRASS documentation and perhaps in GUI tooltips. This is to distinguish the Project folder and concept from the other uses of this common word.
For commands, lower case project is good. And case insensitive is even better so that, for example g.mapsets project= , g.mapsets Project= , g.mapsets PROJECT= all are recognized as the same.
The same thing would go for any use in C or Python code.
Since you are doing a batch replace of Location, this should be pretty easy--except for having to manually look at "location" in documentation to see what is meant (the same thing I suggest to avoid).
We can't police how other people should write this outside of official GRASS documentation, though we have (or should have) standards for writing documentation for commands.