I totally agree that the documentation is poor and it took me quite some time to understand what is going on.
I recorded a rosbag for "velodyne_points" topic using a Velodyne VLP-16. The recorded message is PointCloud2 type. Since the recorded file was really large it gave me a lot of trouble even when only trying to take a look at it(initially I had it converted to .csv and used -010 Editor- to read but csv format turned out useless for me).
What worked was that when I converted this bag file to .pcd format. Take a look at this link for that:
https://answers.ros.org/question/235063/bag-file-to-pcd-files/
Then I took a look at one of the .pcd files and used the info in the following link to understand what is in it:
http://pointclouds.org/documentation/tutorials/pcd_file_format.php#pcd-file-format
After these steps I understood what the PointCloud2 message is about...
So the incoming data in that array you asked about is a 1-D array. That is the reason the height is 1. It is called an unordered or unorganized point cloud data. The ring field tells which one of the 16 lasers in VLP-16 is used (though it is different than the laser numbers in the hardware manual), for your case it should be between 0-63.
The datatype tells whether the fields are float, uint16, int8 etc. After taking a look at the .pcd file I understand that the x,y,z,intensity fields are 4 bytes representation of a floating point number (little endian in your message). The ring value is a uint16(unsigned short).
The count is how many of that datatype is there. So you have 4 byte long 1 x, 4 byte long 1 y, 4 byte long 1 z, 4 byte long 1 intensity and 2 byte long 1 ring fields.
Offset tells at which byte the related field starts. For example offset x is 0 so x is 235 171 54 190 in little endian. Then y starts at 4, which is 53 107...
Here is the header of my .pcd file:
.PCD v0.7 - Point Cloud Data file format
VERSION 0.7
FIELDS x y z _ intensity ring _
SIZE 4 4 4 1 4 2 1
TYPE F F F U F U U
COUNT 1 1 1 4 1 1 10
WIDTH 26326
HEIGHT 1
VIEWPOINT 0 0 0 1 0 0 0
POINTS 26326
DATA binary
It tells that there are empty bytes after z and ring fields. After z field there are 4 empty bytes (that is why intensity has an offset of 16, not 12), and after ring there are 10 empty bytes.
point_step is the length of a point in bytes says the PointCloud2 document. It is as follows:
4 bytes (x) + 4 (y) + 4 (z) + 4 (empty) + 4 (intensity) + 2 (ring) + 10 (empty) = 32
row_step is the length of a row in bytes, which is 66811 points (width) * 32 bytes = 2137952