// The prediction result proto for Person/Vehicle Detection.
message OccupancyCountingPredictionResult {
// Current timestamp.
google.protobuf.Timestamp current_time = 1;
// The entity info for annotations from the processor.
message Entity {
// Label id.
int64 label_id = 1;
// Human readable string of the label.
string label_string = 2;
}
// Identified box contains location and the entity of the object.
message IdentifiedBox {
// An unique id for this box.
int64 box_id = 1;
// Bounding Box in the normalized coordinates.
message NormalizedBoundingBox {
// Min in x coordinate.
float xmin = 1;
// Min in y coordinate.
float ymin = 2;
// Width of the bounding box.
float width = 3;
// Height of the bounding box.
float height = 4;
}
// Bounding Box in the normalized coordinates.
NormalizedBoundingBox normalized_bounding_box = 2;
// Confidence score associated with this box.
float score = 3;
// Entity of this box.
Entity entity = 4;
// A unique id to identify a track. It must be consistent across frames.
// It only exists if tracking is enabled.
int64 track_id = 5;
}
// A list of identified boxes.
repeated IdentifiedBox identified_boxes = 2;
// The statistics info for annotations from the processor.
message Stats {
// The object info and count for annotations from the processor.
message ObjectCount {
// Entity of this object.
Entity entity = 1;
// Count of the object.
int32 count = 2;
}
// Counts of the full frame.
repeated ObjectCount full_frame_count = 1;
// Message for Crossing line count.
message CrossingLineCount {
// Line annotation from the user.
StreamAnnotation annotation = 1;
// The direction that follows the right hand rule.
repeated ObjectCount positive_direction_counts = 2;
// The direction that is opposite to the right hand rule.
repeated ObjectCount negative_direction_counts = 3;
}
// Crossing line counts.
repeated CrossingLineCount crossing_line_counts = 2;
// Message for the active zone count.
message ActiveZoneCount {
// Active zone annotation from the user.
StreamAnnotation annotation = 1;
// Counts in the zone.
repeated ObjectCount counts = 2;
}
// Active zone counts.
repeated ActiveZoneCount active_zone_counts = 3;
}
// Detection statistics.
Stats stats = 3;
// The track info for annotations from the processor.
message TrackInfo {
// A unique id to identify a track. It must be consistent across frames.
string track_id = 1;
// Start timestamp of this track.
google.protobuf.Timestamp start_time = 2;
}
// The dwell time info for annotations from the processor.
message DwellTimeInfo {
// A unique id to identify a track. It must be consistent across frames.
string track_id = 1;
// The unique id for the zone in which the object is dwelling/waiting.
string zone_id = 2;
// The beginning time when a dwelling object has been identified in a zone.
google.protobuf.Timestamp dwell_start_time = 3;
// The end time when a dwelling object has exited in a zone.
google.protobuf.Timestamp dwell_end_time = 4;
}
// Track related information. All the tracks that are live at this timestamp.
// It only exists if tracking is enabled.
repeated TrackInfo track_info = 4;
// Dwell time related information. All the tracks that are live in a given
// zone with a start and end dwell time timestamp
repeated DwellTimeInfo dwell_time_info = 5;
}
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-08-11。"],[],[],null,["# Occupancy analytics guide\n\nThe **Occupancy analytics** model lets you count people or vehicles given\nspecific inputs you add in video frames. Compared with the Person Vehicle\nDetector model, advanced features are provided in the Occupancy Analytics model.\nThese features are active zones counting, line crossing counting, and dwelling\ndetection.\n\n- Active zones let users count people or vehicles in specific user-defined zones.\n- Line crossing provides the ability to count the direction in which an object crosses a particular line.\n- Dwell time detection builds on active zones and provides the ability to detect whether or not objects have remained in a zone for a minimal amount of time.\n\nThe model accepts a video stream as input and outputs a\n[protocol buffer](https://developers.google.com/protocol-buffers/docs/overview) with a count of detected people and vehicles\nin each frame. The model runs at six FPS.\n\nUse case: Smart city traffic analytics\n--------------------------------------\n\nThe following video shows how you can use Vertex AI Vision to create, build,\nand deploy an occupancy analytics application.\n\nThis application uses a model\ncounts cars that cross lines in intersections that the user specifies in the\nGoogle Cloud console. Additionally, the application uses\na person blur model to protect the identity of anyone that appears in the\nvideo feed sources.\n\nThe application sends analyzed data to a Vertex AI Vision's Media Warehouse\nfor media storage, and also to BigQuery to store structured data in a\ntable. The warehouse lets you search stored data on criteria from the\nmodels, such as number of vehicles or people. The table data in\nBigQuery lets you query the data for analytic information. \n\nModel output\n------------\n\nPerson Vehicle Detection shows the number of people and vehicles detected in\nthe current processed frame. The type of count is based on user-provided\nannotation input. The raw detection and tracking results are also in the output.\nBelow is the [protocol buffer](https://developers.google.com/protocol-buffers/docs/overview) definition of the processor\noutput. The frequency of the output stream is constant: three frames per second. \n\n```\n// The prediction result proto for Person/Vehicle Detection.\nmessage OccupancyCountingPredictionResult {\n\n // Current timestamp.\n google.protobuf.Timestamp current_time = 1;\n\n // The entity info for annotations from the processor.\n message Entity {\n // Label id.\n int64 label_id = 1;\n // Human readable string of the label.\n string label_string = 2;\n }\n\n // Identified box contains location and the entity of the object.\n message IdentifiedBox {\n // An unique id for this box.\n int64 box_id = 1;\n // Bounding Box in the normalized coordinates.\n message NormalizedBoundingBox {\n // Min in x coordinate.\n float xmin = 1;\n // Min in y coordinate.\n float ymin = 2;\n // Width of the bounding box.\n float width = 3;\n // Height of the bounding box.\n float height = 4;\n }\n\n // Bounding Box in the normalized coordinates.\n NormalizedBoundingBox normalized_bounding_box = 2;\n\n // Confidence score associated with this box.\n float score = 3;\n\n // Entity of this box.\n Entity entity = 4;\n\n // A unique id to identify a track. It must be consistent across frames.\n // It only exists if tracking is enabled.\n int64 track_id = 5;\n }\n\n // A list of identified boxes.\n repeated IdentifiedBox identified_boxes = 2;\n\n // The statistics info for annotations from the processor.\n message Stats {\n // The object info and count for annotations from the processor.\n message ObjectCount {\n // Entity of this object.\n Entity entity = 1;\n // Count of the object.\n int32 count = 2;\n }\n\n // Counts of the full frame.\n repeated ObjectCount full_frame_count = 1;\n\n // Message for Crossing line count.\n message CrossingLineCount {\n // Line annotation from the user.\n StreamAnnotation annotation = 1;\n // The direction that follows the right hand rule.\n repeated ObjectCount positive_direction_counts = 2;\n // The direction that is opposite to the right hand rule.\n repeated ObjectCount negative_direction_counts = 3;\n }\n\n // Crossing line counts.\n repeated CrossingLineCount crossing_line_counts = 2;\n\n // Message for the active zone count.\n message ActiveZoneCount {\n // Active zone annotation from the user.\n StreamAnnotation annotation = 1;\n // Counts in the zone.\n repeated ObjectCount counts = 2;\n }\n\n // Active zone counts.\n repeated ActiveZoneCount active_zone_counts = 3;\n }\n\n // Detection statistics.\n Stats stats = 3;\n\n // The track info for annotations from the processor.\n message TrackInfo {\n // A unique id to identify a track. It must be consistent across frames.\n string track_id = 1;\n // Start timestamp of this track.\n google.protobuf.Timestamp start_time = 2;\n }\n\n // The dwell time info for annotations from the processor.\n message DwellTimeInfo {\n // A unique id to identify a track. It must be consistent across frames.\n string track_id = 1;\n // The unique id for the zone in which the object is dwelling/waiting.\n string zone_id = 2;\n // The beginning time when a dwelling object has been identified in a zone.\n google.protobuf.Timestamp dwell_start_time = 3;\n // The end time when a dwelling object has exited in a zone.\n google.protobuf.Timestamp dwell_end_time = 4;\n }\n\n // Track related information. All the tracks that are live at this timestamp.\n // It only exists if tracking is enabled.\n repeated TrackInfo track_info = 4;\n\n // Dwell time related information. All the tracks that are live in a given\n // zone with a start and end dwell time timestamp\n repeated DwellTimeInfo dwell_time_info = 5;\n}\n```\n\nBest practices and limitations\n------------------------------\n\n- Avoid unusual camera viewpoints (for example, a top-down view) where people and vehicles appear differently from a standard or common view of them. The detection quality can be largely impacted by unusual views.\n- Ensure that people and vehicles are fully or mostly visible. The detection quality can be affected by partial occlusion by other objects.\n- The person vehicle detector has a minimal detectable object size. This size is approximately 2% with respect to the size of the camera view. Ensure that the target people and vehicles aren't too far away from the camera. These key objects' viewable sizes must be sufficiently large.\n- Areas of interest must have proper lighting.\n- Ensure the video source camera lens is clean.\n- Ensure entities (other than people or cars) don't obstruct any part of the camera's field of view.\n- The following factors might degrade the model's performance. Consider these factors when you source data:\n - Poor lighting conditions.\n - Crowdedness and object occlusions.\n - Uncommon or less common viewpoints.\n - Small object sizes."]]