Overview of protobuf, common use cases, and implementation details.
protobuf
) is a schema definition language with an efficient binary format and native language support for lots of languages, including Go.
Protocol buffers are open source since 2008 and are maintained by Google.
.proto
file, and then converted to a native Go struct using the protobuf compiler.
Tilebox datasets already define a protobuf schema as well, and automate the generation of Go structs for existing datasets through a quick tilebox-generate
command-line tool.
See Installation for more details on how to install tilebox-generate
.
./protogen/tilebox/v1/sentinel1_sar.pb.go
file. More flags can be set to change the default output folders, package name, etc.
This file contains everything needed to work with the Sentinel-1 SAR dataset.
It’s recommended to check the generated files you use in your version control system.
If you open this file, you will see that it starts with // Code generated by protoc-gen-go. DO NOT EDIT.
.
It means that the file was generated by the protoc-gen-go
tool, which is part of the protobuf compiler.
After editing a dataset, you can call the generate command again to ensure that the changes are reflected in the generated file.
The file contains a Sentinel1Sar
struct, which is a Go struct that represents a datapoint in the dataset.
v1.Sentinel1Sar
message.
proto.String
is a helper function that converts string
to *string
.
This allows protobuf to differentiate between a field that is set to an empty string and a field that is not set (nil).
An exhaustive list of those helper functions can be found here.
Only primitives have a proto.XXX
helper function.
Complex types such as timestamps, durations, UUIDs, and geometries have a constructor function.
CheckValid
methodCheckValid
returns an error if the field is invalid.
IsValid
methodIsValid
reports whether the field is valid. It’s equivalent to CheckValid == nil
.
AsXXX
methodsAsXXX
methods convert the field to a more user friendly type.
AsUUID
will convert a datasetsv1.UUID
field to a uuid.UUID typeAsTime
will convert a timestamppb.Timestamp
field to a time.Time typeAsDuration
will convert a durationpb.Duration
field to a time.Duration typeAsGeometry
will convert a datasetsv1.Geometry
field to an orb.Geometry interfaceIsValid
or CheckValid
methods.
for
loop.
As an example, here is how to extract the copernicus_id
fields from the datapoints.
proto.Message
.